Troubleshooting

Common issues and how to resolve them.

Deployment Issues

Build Fails

If your app fails to build:

1. Check build logs — go to your app's detail page and click View Logs to see compiler output.
2. Verify environment variables — missing build-time variables (e.g. DATABASE_URL for Prisma) will cause failures. Go to App Settings > Environment and check all required vars are set.
3. Check dependencies — ensure your package.json, Cargo.toml, or equivalent lock file is committed and up to date.
4. Framework version — Kapable supports Node.js 20+, Rust stable, and Python 3.11+. Check your runtime requirements match.

App Shows "Unhealthy"

Your app deployed but isn't responding:

1. Check app logs — look for startup errors, panics, or binding issues.
2. Verify the port — your app must listen on the port provided in the PORT environment variable. Hardcoded ports won't work.
3. Startup time — apps have 30 seconds to start responding to health checks. If your app needs longer, consider optimizing startup or using a lighter health endpoint.
4. Memory limits — apps on the Free plan have 512MB RAM. Check for memory leaks or large startup allocations.

Custom Domain Not Working

1. DNS propagation — CNAME changes can take up to 48 hours to propagate. Use dig CNAME yourdomain.com to check.
2. Verify CNAME target — it should point to your-app-slug.kapable.run.
3. SSL certificate — certificates are issued automatically via Let's Encrypt. It may take a few minutes after DNS verification. Check the domain status in App Settings > Domains.
4. TXT record — if domain verification is pending, ensure the TXT record matches exactly what's shown in the console.

"503 Service Unavailable"

This means the app exists but isn't currently serving traffic:

• Paused — check if the app was paused. Click Resume in the app detail page.
• Building — a new deployment may be in progress. Check the deployment timeline.
• Crashed — the app process exited. Check logs for the crash reason and redeploy.

Authentication Issues

Can't Log In

1. Check your email — magic links are sent to the email you signed up with. Check spam/junk folders.
2. Link expiry — magic links expire after 10 minutes. Request a new one if yours has expired.
3. Browser cookies — Kapable uses secure cookies. Ensure cookies are enabled and you're not in a browser mode that blocks them.
4. Correct organisation — if you belong to multiple orgs, ensure you're logging into the right one at {org-slug}.kapable.ai.

SSO Not Working

1. Client ID and Secret — verify these match exactly what your identity provider shows. Trailing whitespace is a common issue.
2. Redirect URI — the redirect URI configured in your IdP must match the one shown in Auth Settings. Copy it exactly.
3. Domain allowlist — if you've configured a domain allowlist, ensure the user's email domain is included.
4. Provider status — check that the provider shows "Active" in Auth Settings. If it shows "Configured" but not "Active", toggle the enable switch.

Session Expired

Sessions expire after extended inactivity. Simply log in again. If sessions are expiring too quickly:

• Check that your browser allows persistent cookies for .kapable.ai
• Ensure your system clock is accurate (clock skew can cause token validation failures)

API Issues

401 Unauthorized

Your API key or session token is invalid:

• Revoked key — check the API Keys page to confirm the key is still active.
• Wrong key — ensure you're using the correct key. Keys are shown only once at creation.
• Header format — use Authorization: Bearer your-key-here (not X-Api-Key or other formats).

403 Forbidden

You're authenticated but lack permission:

• Role check — your role may not have the required permission. Ask an org owner to check your role in Members. See Roles & Permissions.
• Org scope — API keys are scoped to one organisation. Ensure you're accessing resources within the correct org.

429 Rate Limited

You're sending too many requests:

• Default limits — Free plan: 60 requests/minute. Starter: 300/min. Pro: 1000/min.
• Retry-After — check the Retry-After header in the response for when to retry.
• Batch operations — if making many sequential calls, consider using bulk endpoints where available.

Billing Issues

Payment Failed

1. Go to Billing and click Manage Subscription to open the Stripe portal.
2. Update your payment method.
3. Stripe will automatically retry the charge.

Plan Limits Reached

If you've hit your plan's app or member limit:

• Upgrade — go to Billing and select a higher plan.
• Clean up — delete unused apps or deactivate inactive members to free up capacity.

Getting Help

If you can't resolve your issue:

• Documentation — browse all guides at docs.kapable.ai
• Email support — contact support@kapable.ai with your org slug and a description of the issue
• Include details — app ID, timestamps, error messages, and screenshots help us resolve issues faster

Next Steps