Troubleshooting

Most onboarding failures print a stable code, a likely cause, a next action, and a docs URL. Start with:

frontier doctor
frontier auth status
frontier update-check

Retrying is safe when the command is read-only (doctor, status, inspect, compare) or when ingest uses the same externalRunId (upload is idempotent). Re-running cdc consume on an empty stream is safe (EMPTY/REUSED). Do not re-run cdc prove --apply until you understand the previous batch.

DBT_ARTIFACT_MISSING — no target/manifest.json. Cause: dbt was not compiled, or compile failed. Run dbt compile, then retry frontier discover. Retrying after a successful compile is safe.

In GitHub Actions, missing target/frontier-artifact-sha or a SHA that does not match GITHUB_SHA means artifacts are stale. The workflow should write the SHA after a successful dbt build. Retrying the whole job is safe; do not reuse another commit's target/.

AUTH_REQUIRED — no env key, keychain, or 0600 file. Run frontier login --api-key.

AUTH_INVALID — key revoked, wrong URL, or unbound to a project. Generate a new key in Settings and login again.

AUTH_CANCELLED — login prompt interrupted. Re-run login. Retrying is safe.

MANIFEST_NOT_FOUND, MANIFEST_NOT_ACTIVE, MANIFEST_IS_DRAFT, MANIFEST_REQUIRED. Cause: discover uploaded a draft that was never activated, or CI ran without frontier manifest fetch. Activate in the dashboard, then re-run CI. Retrying without activation is not useful.

MANIFEST_FINGERPRINT_MISMATCH, MANIFEST_VERSION_MISMATCH, MANIFEST_LOCAL_REMOTE_CONFLICT, MANIFEST_TARGET_MODEL_MISSING, MANIFEST_ENTITY_KEY_ABSENT, MANIFEST_GRAIN_INCOMPATIBLE, MANIFEST_LOW_CONFIDENCE, MANIFEST_ROUTE_UNCONFIRMED, MANIFEST_TEMPORAL_INCOMPLETE. Cause: the pinned snapshot does not match compiled dbt or still has unconfirmed inferred routes. Confirm routes, activate a new version, fetch again. Retrying the same pin will fail the same way.

DISCOVER_NO_MODELS / DISCOVER_MODEL_UNKNOWN — pass --model for the mart you want. MANIFEST_DRAFT_FAILED — SaaS rejected the inferred document; review the mapping. PROJECT_NOT_FOUND — local project name does not match SaaS.

SAAS_UNREACHABLE / MANIFEST_SAAS_UNAVAILABLE. Confirm FRONTIER_API_URL in .frontier/config.yml and that CI uses a public HTTPS origin. Retrying is safe after network recovery.

RUNNER_UNSUPPORTED — installed CLI is below the hosted minimum. Upgrade with pipx install "frontier-runner[snowflake]==0.1.1". Frontier does not auto-update. Retrying the old binary will keep failing.

Connection errors mention missing SNOWFLAKE_ACCOUNT / user / password or dbt profile outputs. Privilege errors mean the CI role cannot SELECT sources or create work tables. Re-run frontier setup snowflake and apply grants. frontier doctor (without --skip-warehouse) pings Snowflake. Retrying after grants is safe.

Frontier will not execute in DBT_PROD — an identifier looks like production (DBT_PROD, PROD, PRODUCTION, or *_PROD). Point CI at DBT_CI / FRONTIER_WORK. Do not retry against production.

The workflow calls frontier record-failure with reason base-branch dbt compile failed. Cause: the base SHA could not compile. Fix base or the worktree compile step. Re-running after a successful base compile is the correct retry.

FULL_REBUILD_REQUIRED on impact compilation, or Impact: full rebuild required on the PR comment. Cause: grouping/grain/window/source/unsupported SQL, or candidate SQL that cannot cover the change. Targeted proof is skipped. Treat as fail-closed and rebuild the model. Distinct from FULL_REBUILD_RECOMMENDED, which is an efficiency warning. Retrying prove without changing SQL will repeat the same decision.

Impact execution FAILED, or prove errors such as SQL-change proof requires compiled base/PR SQL and affected keys, target SQL cannot be safely filtered, or no candidate keys to materialize (CDC). Cause: warehouse execution failed or compiled SQL is not filter-safe. Check Snowflake history and frontier doctor. Retrying is safe after the SQL or grants are fixed; repeating a known unsafe filter is not.

Upload failed with HTTP 429 or 5xx — the runner retries up to four times. Retrying the upload command is safe; ingest is keyed by externalRunId.

HTTP 413 or a payload that includes forbidden row/entity fields is rejected immediately. Shrink the assessment or keep entity hashing enabled. Do not retry a payload that contains raw rows.

MANIFEST_API_KEY_REVOKED during fetch/upload — login with a new key.

Upload succeeded and printed the dashboard id, then the process exited 1 because FRONTIER_BLOCKING=true and status was failed. The run is already stored. Open it, fix the underlying failure, and push another commit. Retrying upload on the same failed file will exit 1 again while blocking is on.

frontier cdc status prints empty. Consume prints status EMPTY and no new batch=. Cause: no pending stream records. Retrying later is safe. Do not prove until a batch exists.

CDC batch not found, no completed CDC batch waiting for upload, completed batch cannot be reprocessed, or CDC stream is already claimed by another consumer. Cause: wrong --batch-id, prove ran before consume, or another worker holds the claim. Check cdc status / control tables. Retry consume after the claim is released. Do not prove a COMPLETED batch again.

BASELINE_STALE — a previous completed CDC assessment was not applied or incorporated into the mart baseline. Apply or rebuild the mart before uploading a new passed CDC assessment. Retrying upload without resolving the baseline will fail again.

GITHUB_REMOTE_MISSING, GITHUB_WORKFLOW_EXISTS, GITHUB_WORKFLOW_INVALID, GITHUB_SECRET_MISSING, CLIPBOARD_UNAVAILABLE. Set a github.com origin, confirm overwrite, or use gh secret set. Retrying after the remote or secret exists is safe.