Reference
Troubleshooting
Diagnose common project, identity, policy, user-presence, automation, provider, and Git-state failures without exposing plaintext values.
Collect safe diagnostics
Start with version, repository, and redacted project state. These commands should not print decrypted values:
$ ghostable --version
$ ghostable status --json
$ git status --short
$ git diff -- .ghostable
Record the operating system, installation method, exact command, exit code, and redacted stderr. Never attach GHOSTABLE_CI_TOKEN, local identity files, generated env files, --show-values output, or provider credentials.
Project not found
Run Ghostable from a repository directory containing .ghostable/ghostable.yaml, or from one of its descendants. If the repository has no manifest, initialize a new project with ghostable setup or pull the branch that contains the reviewed .ghostable/ state.
$ git rev-parse --show-toplevel
$ git status --short -- .ghostable
Do not copy another project's manifest to fix discovery. Its project ID is a cryptographic boundary, not a reusable template value.
Identity and policy errors
-
Identity registered to another path - This checkout or worktree is a different canonical root. Join it as a new device instead of copying private identity material.
-
Device has been revoked - The old identity is permanently unusable. Join with --force to create a new identity, then request access again.
-
Policy signer is not trusted or policy is stale - Fetch and review the latest policy and access commits from the authoritative branch. Never lower a trusted policy version or repair signatures by hand.
-
Invalid signature - Stop and inspect Git history. Restore one complete reviewed record generation or replay the Ghostable operation from clean state.
$ unset GHOSTABLE_CI_TOKEN
$ ghostable access join --force --name "Replacement workstation"
On PowerShell, remove an accidentally inherited automation token with Remove-Item Env:GHOSTABLE_CI_TOKEN before joining as a human device.
User-presence failures
Protected plaintext operations require an interactive local session. Retry from a terminal attached to the signed-in desktop session and complete Touch ID, Windows Hello, or the local PAM-backed confirmation. SSH sessions, background services, redirected input, and headless jobs generally cannot satisfy the prompt.
Use a dry run when it is sufficient. For CI or deployment automation, create a narrowly scoped automation credential instead of attempting to bypass local user presence.
Automation token failures
-
Missing token - Bind GHOSTABLE_CI_TOKEN through the job secret environment, not as a CLI argument or echoed shell value.
-
Invalid prefix or malformed token - Replace the secret from its trusted source. Tokens cannot be reconstructed from repository records.
-
Project ID mismatch - The token belongs to another Ghostable project. Confirm the checkout and create a project-scoped replacement.
-
Revoked credential - Create a new credential, commit its public records, update the job secret, and remove the old secret.
-
Permission denied - Inspect access matrix and grant only the required environment and reader or writer role.
Do not expose protected tokens to forked or unreviewed pull-request code. Use credential-free review --secrets-only for that trust boundary.
Provider CLI failures
A Ghostable provider dry run does not invoke the provider CLI, query remote state, or test authentication. For a real deployment, confirm the expected forge, vapor, or cloud executable is on PATH, outside the application repository, and authenticated in the same user or runner context.
$ forge --help
$ vapor --help
$ cloud --help
If a provider push fails, treat its stderr as potentially sensitive, verify the remote environment before retrying, and inspect OS temporary storage after abrupt runner termination. Ghostable redacts known values from provider failures, but transformed provider output may still require manual redaction.
Git conflicts
Do not hand-merge signed records. Follow the repository conflict runbook to select one complete record generation, replay the discarded Ghostable operation, and verify status, validation, review, and the final Git diff.