Troubleshooting

Solutions to common issues with OrbitKit accounts, apps, policies, deployment, and billing.

Common issues and their solutions, organized by category.

Account

Can’t log in

Symptom: You see “Invalid email or password” or “User not found.”

Solutions:

Verify you’re using the email you signed up with
Use the Forgot Password link on the sign-in page to reset your password
Check that your browser isn’t blocking cookies (Firebase Auth requires them)
Clear browser cache and try again

Email verification not arriving

Symptom: You signed up but didn’t receive a verification email.

Solutions:

Check your spam/junk folder
Make sure you entered the correct email when signing up
Request a new verification email from the account settings page
Add noreply@orbitkit.io to your contacts to prevent filtering

Password reset not working

Symptom: Reset email link says “expired” or “invalid.”

Solutions:

Password reset links expire after 1 hour — request a new one
Make sure you’re clicking the most recent link (earlier ones are invalidated)
If you still can’t reset, contact support@orbitkit.io

Apps

App limit reached

Symptom: Error APP_LIMIT_REACHED when creating a new app.

Cause: OrbitKit allows a maximum of 10 apps per account.

Solutions:

Delete apps you no longer need from the dashboard
If you need more than 10 apps, contact support@orbitkit.io

Slug conflicts

Symptom: Error SLUG_TAKEN when creating an app or changing the slug.

Cause: Another user already has that slug. Slugs are globally unique.

Solutions:

Try a more specific name (e.g., “my-weather-app” instead of “weather”)
Add a prefix like your company name

Image upload fails

Symptom: Icon upload returns VALIDATION_FAILED.

Cause: The image doesn’t meet requirements.

Solutions:

Use PNG, JPEG, or WebP format (other formats are not supported)
Keep file size under 2 MB
Ensure the image is not corrupt or zero-length
Set the correct Content-Type header (image/png, image/jpeg, or image/webp)

Privacy Policy

Wizard not saving

Symptom: Changes in the privacy wizard don’t persist after refreshing.

Solutions:

Check your internet connection — the wizard saves to the server, not locally
Look for error banners at the top of the wizard
Open browser dev tools (Console tab) and check for network errors
Try signing out and back in

Missing data categories

Symptom: The policy doesn’t include data types you selected.

Cause: The wizard requires you to set the “Does your app collect data?” gate to “Yes” before data types are included.

Solutions:

In the Data Collection step, make sure “Does your app collect data?” is set to Yes
Re-select your data types and purposes after changing this setting

Deployment

Deploy fails

Symptom: Error DEPLOY_FAILED or SUBSCRIPTION_REQUIRED.

Solutions:

SUBSCRIPTION_REQUIRED: Subscribe the app first (Dashboard > App > Subscribe)
DEPLOY_FAILED: Try deploying again — temporary server errors resolve on retry
Make sure you’ve completed the privacy policy wizard (at minimum, the app-info section)
If deploys fail repeatedly, contact support@orbitkit.io with the request ID from the X-Request-Id header

Site not updating after deploy

Symptom: Your deployed site shows old content.

Cause: Browser caching or CDN propagation delay.

Solutions:

Hard refresh your browser (Cmd+Shift+R / Ctrl+Shift+R)
Try viewing the site in an incognito/private window
Wait 2–5 minutes for CDN caches to update
Verify the deploy succeeded by checking deploy history in the dashboard

Custom domain SSL issues

Symptom: Browser shows “Not Secure” or SSL certificate errors on your custom domain.

Solutions:

Check domain status via Dashboard or API (GET /api/apps/:appId/site/domain/status)
pending_dns: DNS records haven’t propagated yet. Verify both the A record and CNAME record are configured at your registrar. DNS can take up to 48 hours.
pending_ssl: DNS is verified but SSL is still provisioning. This usually takes 15–60 minutes after DNS propagation.
error: Double-check your DNS records match the instructions exactly. Remove and re-add the domain if records are correct but status is stuck.
Make sure you don’t have a conflicting AAAA (IPv6) record for the same domain

Billing

Payment declined

Symptom: Error CARD_ERROR or PAYMENT_ERROR when subscribing.

Solutions:

Verify your card details are correct
Check that your card has not expired
Contact your bank — they may be blocking the charge
Try a different payment method
Update your payment method via the account settings page

Subscription not activating

Symptom: You completed payment but the app still shows “Subscribe.”

Cause: 3DS authentication may not have completed, or the webhook hasn’t processed yet.

Solutions:

If you were redirected to a 3DS verification page, make sure you completed it
Wait 30 seconds and refresh the page — webhook processing can take a moment
Check your account status via GET /api/status to confirm the subscription state
If the issue persists, contact support@orbitkit.io with your email address

Invoice questions

Symptom: Need to access past invoices or have billing questions.

Solutions:

View invoices via Dashboard > Account > Billing, or GET /api/invoices
Open the Stripe Billing Portal via Dashboard > Account > Manage Billing for self-service invoice management
For refund requests or billing disputes, email support@orbitkit.io

Still need help?

Email support@orbitkit.io with:

Your account email
The app name and slug (if app-specific)
The X-Request-Id header value (if you have it from an API error)
A description of what you expected vs. what happened