🔧 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.

App crashes immediately on launch

Symptom: You install the APK but it crashes before showing any UI.

Common causes:

• Missing Application class — If your code references a custom Application class (e.g. WorkoutApp), the AndroidManifest.xml must have android:name=".WorkoutApp" on the <application> tag. Without it, the cast in MainActivity throws a ClassCastException.
• Missing dependencies — If using Room, ensure the KSP plugin is in both the top-level and app-level build.gradle.kts.
• Namespace mismatch — The package in build.gradle.kts must match the package statement in your .kt files.

Fix: Ask the wizard to fix the specific error, or manually edit the manifest and rebuild.

App shows as "SaaSClaw" instead of my project name

Symptom: The installed app shows "SaaSClaw" on the home screen instead of your project name.

Fix: The deploy pipeline automatically replaces "SaaSClaw" with your project's display name. If you still see "SaaSClaw," redeploy — the fix runs on every Android deploy.

Deploy button finishes instantly

Symptom: The 🚀 Deploy button in the wizard returns a success dialog almost immediately.

Cause: This is expected behavior for static and Node.js projects — they only copy files, no compilation needed. Android projects run a full Gradle build (~12-60 seconds).

Check: If an Android deploy finishes instantly, verify the project's runtime kind is set to android in the environments.

401 authentication error in mobile app

Symptom: The SaaSClaw mobile app shows a 401 error or won't load projects.

Fix:

• The app automatically refreshes expired tokens. If the refresh token is also expired (after 7 days), the app returns to the login screen.
• Log out from the Account screen and log back in with your credentials.
• If the error persists, check that your user account is active and the password is correct.

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.