For AI agents: the complete documentation index is available at https://docs.flezise.com/llms.txt, the full documentation bundle is available at https://docs.flezise.com/llms-full.txt, and this page is available as Markdown at https://docs.flezise.com/reference/troubleshooting.md.
Docs

Troubleshooting

Start here when a project stalls:

swecli me                          # your projects and pending-action counts
swecli action list --all-projects  # everything waiting on you
swecli docs search "<your words>"

Nothing is generating

Onboarding finished but no documents appeared

The product brief must be approved before the workflow design generates, and the workflow design must be approved before the rest of the pipeline runs.

  1. swecli artifact list --project <slug> status=in_review to see what is waiting on approvers.
  2. Open the artifact and press Approve, or swecli artifact approve <id> --comment "Approved.".
A document was generated and then nothing happened

Generation stops at draft. Nothing promotes a draft on its own.

  1. swecli artifact list --project <slug> status=draft
  2. Open the artifact and press Submit for Review in the header. After a reviewer sends it back, the button reads Resubmit for Review.
The Submit for Review button is disabled

The button is disabled when a generation is still running for that artifact. The generation_context.status field will be generating, pending, or queued.

  1. Wait for the generation to finish, or press Regenerate in the artifact's ⋮ menu to cancel and restart.
  2. If the status is failed, the generation did not complete. Press Regenerate or ask the builder agent to re-run.

A run failed

A generation run produced nothing
  1. swecli run list --project <slug> status=failed --limit 5, or open /projects/<slug>/runs (also Settings → Run History) and filter Failed.
  2. Expand the row to see Trigger, Task, and Error. View artifact event timeline opens the artifact on its Events tab.
  3. Re-run it: press Regenerate in the artifact's ⋮ menu, or ask Atlas to re-run the failed node.

A run marked Dead-lettered failed repeatedly and will not be retried automatically. The draft is kept and a notification names it. Regenerate it deliberately once you have fixed the cause.

A work item is in failed state

Board → the card's ⋮ menu → Retry execution, or select several cards and press Retry in the bulk action bar. A retry re-dispatches to executing without re-planning.

A stuck triage is a different failure: open the work item page, find the triage card, and press Retry triage. Retrying execution does nothing for a triage failure.

An approval is blocked

The Approve button is greyed out

Hover it: the tooltip is the server's reason, verbatim. Or:

swecli action list kind=artifact_approval --project <slug> --fields id,title,actionable,blocking_reason
ReasonWhat to do
Resolve N review item(s) before approval.Open the artifact → Review tab → resolve each item. This check masks every other reason.
You already approved this level.Wait for the other approvers at this level, or ask a Project Admin.
Approval level N is assigned to <names>.Ask them, or change the policy under Settings → Approvals.

Project Admins can approve at any level they have not already voted at.

Approval is blocked by stale upstream dependencies

A document the artifact depends on changed after it was approved, so the artifact is flagged stale and approval refuses to proceed. Regenerate the artifact so it reflects the change, then submit it again.

Drift

A document no longer matches the implementation

Use Regenerate in the artifact's ⋮ menu, Regenerate stale (N) on the artifact tree for pages flagged stale, the source-change badge with Check drift on a design canvas, or ask Atlas to check for drift and regenerate.

Deployment

AUTH_ENABLED=true and the backend refuses to start

Auth needs two secrets: INTERNAL_API_KEY and LOGTO_WEBHOOK_SECRET. On Docker Compose, scripts/gen-secrets.sh writes both into .env and never overwrites existing values. Without the webhook secret, identity webhooks are refused with a 503.

A code or prompt change is not taking effect

Celery workers do not hot-reload. Restart the affected worker after changing tasks, skills, or personas. Prompt templates on disk reload through the marketplace's POST /api/reload. Changes under harness/ need a rebuilt sandbox image.

A new /api route answers from the wrong service

Routes are declared in both the Compose nginx config (deploy/nginx/nginx.conf) and the Helm nginx ConfigMap. Any /api/ path not in either explicit list falls through to the AI gateway.

Request Tracing shows nothing

The gateway must run with log_store enabled. The screen says so in its error state.

Getting help

Open Atlas (Agent, bottom-right) and describe the symptom. It reads status, explains the block in the server's words, and can act as you after confirming. The audit trail at /projects/<slug>/audit shows what happened, by whom, in sequence.