🔧 Troubleshooting

The wizard is stuck or generating too long

Symptom: The wizard keeps generating code without stopping, or the response is taking very long.

Fix: Click the Stop button to halt the current generation. Your code up to that point is preserved. Then send a new message to redirect the wizard.

Stale or unresponsive session

Symptom: The wizard shows an old session, messages aren't sending, or the wizard doesn't respond.

Fix:

• End the current session from the session controls.
• Start a new session from the project page.
• If the problem persists, check the Ops panel (/ops/) to see if the agent process is running. Use the kill button if needed.

The wizard's response doesn't match my request

Symptom: The wizard generates code that doesn't align with what you asked for.

Fix:

• Be more specific — instead of "add auth," say "add JWT-based authentication with login and registration pages using Django's built-in User model."
• Break complex features into smaller steps. Build the core first, then add features one at a time.
• Use Stop and redirect: "Stop — instead, create a simple REST API with two endpoints: /items (GET) and /items (POST)."

Build failure after deploy

Symptom: Deploy starts but the build step fails. App doesn't start.

Fix:

• Check the build logs on the project page for specific error messages.
• Missing dependencies: Ensure requirements.txt, package.json, or go.mod includes all needed packages.
• Syntax errors: Review recently generated files for typos or syntax issues.
• Port issues: Ensure your app listens on the port SaaSClaw assigns (check environment variables).
• Fix the issue in the wizard, then redeploy.

Merge conflict after multiple sessions

Symptom: After multiple wizard sessions, files conflict when trying to deploy.

Fix:

• Open the Editor from the project page to manually resolve conflicts.
• Or start a new wizard session and ask the wizard to resolve the conflicts: "There are merge conflicts in these files — please resolve them."
• Prevention: End sessions properly after each iteration so code is committed cleanly.

Production deploy not updating

Symptom: Clicked 🚀 Prod but the production site shows old code.

Fix:

• Verify the production deploy completed (check deploy history for status).
• Clear your browser cache or use incognito mode to test.
• If the deploy failed silently, check deploy history and retry.

Domain verification fails

Symptom: "Verify" button returns an error. Domain won't activate.

Fix:

• Double-check the CNAME record: your-domain.com CNAME <slug>.saasclaw.app
• Wait longer — DNS can take up to 48 hours to propagate (usually 5–30 min).
• Use dig your-domain.com CNAME or an online DNS checker to verify the record exists.
• Ensure you created a CNAME, not an A record.

Can't create a new project

Symptom: "Create Project" button doesn't work or returns an error.

Fix:

• Make sure you're logged in.
• Check that the project slug doesn't conflict with an existing project.
• If you see a permissions error, contact your administrator.

API key errors in the wizard

Symptom: the wizard responds with "API key not found" or authentication errors.

Fix:

• Go to Settings and verify your AI provider API key is set correctly.
• Check that the key hasn't expired or been revoked at the provider.
• Try a different provider using the Provider dropdown on the project page.