Troubleshooting
Start with the symptom. Most issues are access, project selection, or a missing approval, not a broken host.A page or tool works for me but not for a customer
- Confirm you are in the right project.
- Preview as that role (do not test only as owner/admin).
- Open App Blueprint → Access for that role; fix Roles, page roles, tool roles, or model access.
- Remember: hiding a nav item does not revoke page access, and a visible nav link still fails if the page excludes the role.
An agent cannot use a tool
- The tool’s allowed roles must include the end user’s role.
- In Chat mode the tool must already exist; switch to Build to add it.
- Sub-agents only get what you configured; they cannot improvise new tools mid-flight.
An automation did not run
- Confirm it is enabled and the schedule is what you expect.
- Open project Executions for errors.
- Check that the automation’s tools are allowed to run in that project context.
An event hook failed
- Hooks should be safe to retry; the original action may have succeeded.
- Read the error in Executions or logs, fix the follow-up tool, and re-trigger if needed.
- Do not assume chat will “remember” to do the follow-up next time.
A background job is stuck
- Open Executions for status and errors.
- Confirm results write to tables or project files as the job progresses.
- For huge imports, prefer smaller batches over one unbounded job.
OAuth disconnected or scopes wrong
- After changing scopes, users must Connect again.
- Confirm the OAuth Redirect URL from App Settings → Integrations matches the provider console.
- Never paste access tokens into chat.
Webhook or inbound route rejected
- Open routes require a bearer token or signed webhook. Open endpoints with no secret are not available.
- Verify the secret or signing configuration on both sides.
Invite not received / portal login stuck
- Check End-Users for the invite status and role.
- Ask the user to check spam; confirm the email spelling.
- If the UI cannot unblock it, email support@genieforge.ai with the app name and what you saw.
Custom domain not verifying or SSL pending
- CNAME and TXT must match Project Settings → Custom Domains exactly.
- Subdomains only for now (not apex
yourcompany.com). - Project must be public for visitors on the custom domain.
- Use Refresh while SSL is pending; contact support if you get a platform configuration error.
Form rejects input or public intake fails
- Format fields (email, phone, URL, date, UUID) must be valid, not only non-empty.
- Public intake needs a dedicated code tool (not a direct data-model create), and is unavailable on HIPAA-enabled apps.
- Guests who hit Back need to open the link or QR again (short-lived session).
Preview differs from what customers see
- Preview as the same role and project.
- Custom domains and registration settings only apply to the live portal path.
- Collaborator (builder) login is not the end-user portal.
Build used far more credits than expected
- Check Credit Usage: Build vs Chat, active build time, spend by person.
- Prefer smaller iterations; avoid rebuilding working surfaces.
- Move bulk work to background tasks.
The AI changed something you did not want
- Use App Blueprint → Versions to roll back the blueprint.
- Capture hard constraints in Build Rules and Documentation.
- Prefer plan approval before large changes; use Fork chat to explore alternatives.