---
title: Clickhouse handling failed migrations in self-hosted Langfuse
seoTitle: "Handle Failed ClickHouse Migrations"
description: "How to recover a self-hosted Langfuse ClickHouse database stuck on a dirty migration version, so further migrations can run again."
tags: [self-hosting]
---

# Clickhouse handling failed migrations in self-hosted Langfuse

If you encounter a migration error, the migration tool will prevent you from running additional migrations on the same database. You'll see an error message like "Dirty database version 1. Fix and force version" even after fixing the erred migration. This means your database has been marked as 'dirty'. You need to investigate whether the migration was partially applied or not applied at all. After determining the actual state, force your database to the version that accurately reflects its current state. Once you've forced the correct version and fixed the migration, your database will be 'clean' again, allowing you to proceed with subsequent migrations.

<Details>
<Summary>Code Example to fix failed migrations</Summary>

Let's assume your migration 16 failed. You have corrected the failed migration. If you try to migrate again, migrate will STILL refuse:

```bash
error: Dirty database version 16. Fix and force version.
```

You will have to force your database to the last successful version, which is 15. Make sure to replace the database credentials with your own.
Before running the command below, make sure you have golang-migrate installed. If you do not, please follow the guide linked in our [contributing guide](https://github.com/langfuse/langfuse/blob/main/CONTRIBUTING.md#development-setup). Then, navigate to the root of your Langfuse project folder in your terminal. Then run the following command:

```bash
migrate -path migrations/ -database clickhouse://test:test@localhost:9000/dummy force 15
```

If you migrate again, the output will now be:

```bash
16/u migration_name (12.718637ms)
```

</Details>

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/faq/all/self-hosting-clickhouse-handling-failed-migrations.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.