Troubleshooting

This page is symptom-first. Search it for the error message you got, then follow the numbered steps under it.

For the opposite view, categories of failure with a recovery playbook for each, see Failure modes.

Compile errors

“unknown dependency ‘X’ referenced by ‘Y’”

Model Y lists X in its depends_on, but the project has no model named X.

Likely causes

• A typo in depends_on. The message adds “did you mean ‘Z’?” when a model name is close.
• The model file for X is missing or misnamed.
• The name field in the .toml sidecar does not match the file name.
• X is a source table, not a model.

Fix

1. Check the spelling against the suggestion in the message.
2. Check that the model file exists under models/ and that its name field matches.
3. Remove the entry when X is a source table. Rocky reads a source table from the SQL; it needs no depends_on.

“join key type mismatch on column ‘X’”

Two upstream models in a join share a column name but not its type, and the types have no common type (E001).

Fix

1. Read the diagnostic. It names both models and both types.
2. Add an explicit CAST() on one side of the join, or change the upstream model to produce the expected type.
3. If the change is intentional schema evolution, run rocky ai-sync to propagate it downstream.

“Contract violation”

A model’s output does not satisfy its data contract (E010–E014). For example: column 'X' type mismatch: contract expects ….

Fix

1. Open the model’s .contract.toml file and read the required columns and types.
2. Choose one side to change. Either update the model to produce the required schema, or update the contract.

LSP and IDE problems

The language server does not start

The VS Code extension cannot connect to rocky lsp.

Likely causes

• The Rocky binary is not installed, or it is not on PATH.
• The rocky.server.path VS Code setting points somewhere wrong.
• The binary is built for another platform, such as a Linux binary on macOS.

Fix

1. Confirm the binary runs at all:

   rocky --version

2. Check which path VS Code is using, under Settings → Rocky → Server Path.

3. Point that setting at the binary you just ran, or put the binary on PATH.

No diagnostics or hover information

The language server connects but shows no types and no errors.

Likely causes

• The workspace root has no models/ directory.
• The models have syntax errors that stop compilation.

Fix

1. Confirm your workspace root contains a models/ directory.
2. Open the Rocky output channel in VS Code, under View → Output → Rocky Language Server.
3. Fix the errors it reports there.

AI command problems

“ANTHROPIC_API_KEY not set”

The AI commands need an Anthropic API key in the environment.

Fix

1. Export the key:

   export ANTHROPIC_API_KEY=sk-ant-...

2. Add the same line to your shell profile (~/.zshrc, ~/.bashrc) so it survives a new shell.

The generated model is wrong

The compile-verify loop retries up to 3 times, and it can still land on wrong SQL.

Fix

1. Rewrite the intent to be more specific. Name the grain, which is what one row of the model represents.
2. Name the key columns and where they come from.
3. State the filter conditions.
4. State the aggregation logic.

“Compilation failed after 3 attempts”

The AI could not produce valid code inside the retry budget.

Fix

1. Split the intent into smaller models. One model per idea.
2. Wire the pieces together with explicit upstream dependencies.

Connection errors

Databricks: “401 Unauthorized”

Likely causes

• The Personal Access Token expired.
• The OAuth M2M credentials are wrong.
• The token has no access to the warehouse you named.

Fix

1. Regenerate the token in your Databricks workspace settings.
2. For OAuth M2M, check the client_id and client_secret values in the adapter block, and the environment variables they read.

Databricks: “Statement execution timeout”

A query ran longer than the configured timeout.

Fix

1. Raise the timeout on the Databricks adapter:

   [adapter.prod]
   type = "databricks"
   timeout_secs = 600  # 10 minutes

2. For a large full-refresh sync, switch the model to an incremental strategy instead of raising the timeout further.

Fivetran: “403 Forbidden”

Fix

1. Check the api_key and api_secret values in the Fivetran adapter block, and the environment variables they read.
2. Confirm the API key has access to the destination_id you configured.

State store problems

The state store is the embedded redb database where Rocky keeps run records, watermarks, and plans.

“State file locked”

Another Rocky process holds the state file lock.

Fix

1. Look for a running Rocky process:

   ps aux | grep rocky

2. If one is running, wait for it or stop it. Two Rocky runs cannot hold the lock at the same time.

3. If none is running, the lock is stale. Remove it:

   rm -f models/.rocky-state.redb.lock

The state store lives at models/.rocky-state.redb by default. Run rocky doctor to confirm the path. A project on the legacy current-directory state file has .rocky-state.redb.lock in the working directory instead.

“State file corrupted”

The embedded redb state file is damaged.

Fix

1. Delete the state file and re-run. This resets every watermark, so the next run is a full refresh:

   rm models/.rocky-state.redb   # legacy projects: rm .rocky-state.redb in the current directory
   plan_id=$(rocky plan --filter client=acme --output json | jq -r .plan_id)
   rocky apply "$plan_id"

Build problems

Building from source runs out of memory

DuckDB’s C++ compilation needs a lot of memory to build Rocky from source.

Fix

1. Install a pre-built binary instead of building from source. This is the fastest fix.

2. If you must build, close other applications first.

3. If that is not enough, add a swap file for the build:

   # Create a 4GB swap file
   sudo fallocate -l 4G /tmp/rocky-swap
   sudo chmod 600 /tmp/rocky-swap
   sudo mkswap /tmp/rocky-swap
   sudo swapon /tmp/rocky-swap
   
   # Build
   cargo build --release
   
   # Clean up
   sudo swapoff /tmp/rocky-swap
   sudo rm /tmp/rocky-swap