# Data troubleshooting

Diagnose managed-data and refresh failures from the earliest boundary that can reject the operation. Preserve the previous active state while investigating; do not edit serving files or pointers manually to make a failed candidate appear active.

## Establish the failing phase

First identify whether the failure occurs during:

1. local project validation;
2. local managed-data planning;
3. object upload and revision staging;
4. project deployment and revision activation;
5. model-table materialization;
6. semantic or dashboard query serving;
7. storage cleanup.

Capture the exact command, project, connection, environment, target, run or deployment ID, revision digest, and relevant server logs. A generic “refresh failed” report without these identities is difficult to correlate safely.

## Planning fails

If `leapview data plan` fails:

- Validate the project and confirm the connection exists and is `managed`.
- Use the connection's resource name, not its title.
- Confirm `--from` points at the intended root and contains every referenced source path.
- Check permissions, symlinks, case sensitivity, and filenames.
- Keep files stable while they are discovered and hashed.
- Confirm the input does not exceed local disk or process limits.

Run the same command again only after the directory is stable. If comparing revisions, ensure `--previous-manifest` is the manifest for the same project connection.

## Sync fails

For `leapview data sync` failures:

- Verify target URL, token, and project/connection authorization.
- Confirm sufficient local, temporary, and backend object-storage capacity.
- Check reverse-proxy request and timeout limits for local resumable uploads.
- Check bucket permissions and multipart lifecycle for direct object-storage uploads.
- Retry resumable transfer without changing the source directory.

The client verifies that a file does not change during transfer. If it changed, create a new plan and revision. Do not suppress the mismatch or relabel an old digest.

## Deployment rejects a revision

The deploy command requires one `connection=sha256:<digest>` pin for every managed connection and rejects duplicates or unknown names.

Confirm that:

- the digest is the canonical lowercase value printed by `data sync`;
- the staged revision belongs to the same project and connection;
- the local project has not added or removed a managed connection since staging;
- the token can deploy and any explicit environment assertion matches the target instance;
- all workspace candidates validate with the pinned inputs.

Use `leapview data revisions list` to confirm the revision is staged and `current` to see which digest remains active.

## Refresh fails before SQL

If a refresh run cannot resolve inputs:

- confirm the workspace lists every source under `spec.uses.sources`;
- confirm the active deployment pins required managed connections;
- verify external connection credentials and network reachability;
- check that model files and source IDs match the active artifact, not only the working tree;
- inspect whether the run was superseded or cancelled by a newer generation.

Troubleshoot the active deployed configuration. A locally fixed file has no effect until it is validated and deployed.

## Model-table SQL fails

Inspect the first failing table and its declared source dependencies. Common causes include:

- renamed or missing source fields;
- invalid casts after source values changed;
- SQL dialect assumptions unsupported by DuckDB;
- unquoted logical source names containing dots;
- a join or expression referencing an undeclared source;
- out-of-disk or temporary-storage exhaustion.

Reproduce with the same source revision in development. Add defensive casts only when null-on-failure is acceptable; otherwise correct the source contract or reject malformed input.

## Refresh succeeds but results are wrong

Treat this as a data correctness incident, not a rendering issue. Compare row count, primary-key uniqueness, null rates, field types, and trusted aggregate totals. Check joins for fact multiplication and verify relationship cardinality.

Use semantic preview/query and explain commands to isolate the model from the dashboard. If direct semantic results are correct, then inspect dashboard filters, selections, aliases, sorting, and limits.

## Cleanup or storage fails

Do not delete Parquet files or DuckLake catalog rows by hand. Check active serving references, in-process query leases, backend permissions, disk capacity, and maintenance dry-run output. A snapshot protected by an active pointer or lease is not eligible for cleanup.

Escalate with the failing run identity, storage backend, dry-run output, and relevant logs. See [`leapview data`](/docs/cli/data), [Refresh Runs API](/docs/api/refresh-runs), and [Storage and recovery](/docs/guides/data/storage-recovery).