Troubleshoot ScenarioX Self-Hosted V1

Start with the package-native read-only commands. Record the release version, timestamp in UTC, affected URL, and any visible trace or session identifier.

./scenariox version
./scenariox status
./scenariox health
./scenariox logs

Configuration validation fails

Run:

./scenariox config-check

Correct the named missing value, unresolved <...> placeholder, unsupported AI provider, or key-file permission error. The command does not print secret values. Do not paste .env into tickets or chat.

Image pull fails

Confirm that Docker is authenticated to ghcr.io, the token has package read access, organization SSO authorization is complete when required, and SCENARIOX_IMAGE_TAG exactly matches the release metadata. Then retry:

./scenariox pull

Do not switch to latest or mix tags from different releases.

A service is not ready

Use the service name printed by health:

./scenariox status
./scenariox health
./scenariox logs <service>

still starting means the readiness endpoint has not succeeded yet.
unhealthy means the readiness endpoint is failing.
not running means the container exited or was never started.
process state only means no readiness probe exists; inspect logs and the user-visible path.

After correcting a reversible dependency or configuration issue, restart only the affected service:

./scenariox restart <service>
./scenariox health

Confirm the organization slug and email match the bootstrap output. Local sign-in is rate-limited, and access tokens expire after 15 minutes. Repeated bootstrap is not a password-reset mechanism.

Inspect auth without exposing credentials:

./scenariox status
./scenariox health
./scenariox logs auth

Workspace provisioning fails

Capture logs for both the session and workspace boundaries:

./scenariox logs session
./scenariox logs workspace-orchestrator
./scenariox logs docker-socket-proxy

Do not mount the Docker socket into workspace-orchestrator or bypass docker-socket-proxy. See Workspace or evaluation failure.

Evaluation or report is delayed

Capture the session identifier and inspect the relevant workers:

./scenariox logs evaluation-service
./scenariox logs reporting-service
./scenariox logs reporting-api
./scenariox health

Do not create a manual score or modify evidence records. Preserve the original session state for support investigation.

Platform or database outage

Use the offline emergency runbooks:

Backup, restore, support-bundle generation, and automated rollback are not available in Self-Hosted V1. Do not claim successful recovery from an uncertified procedure.