> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genieforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common GenieForge issues: role access, automations, OAuth, domains, forms, credits, and unexpected Build changes.

# 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

1. Confirm you are in the right **project**.
2. **Preview as** that role (do not test only as owner/admin).
3. Open **App Blueprint → Access** for that role; fix Roles, page roles, tool roles, or model access.
4. Remember: hiding a nav item does not revoke page access, and a visible nav link still fails if the page excludes the role.

See [Roles and access control](/users-and-access/roles-and-access-control) and [Reviewing app access](/users-and-access/reviewing-app-access).

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

See [Connected accounts](/integrations/connected-accounts).

## 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](mailto: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.

See [Custom domains](/projects-and-domains/custom-domains).

## 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).

See [Forms](/primitives/forms).

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

See [Controlling credits](/account/controlling-credits).

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

## Still stuck

Email [support@genieforge.ai](mailto:support@genieforge.ai) with app name, project, role, what you tried, and any error text. Privacy requests go to [privacy@genieforge.ai](mailto:privacy@genieforge.ai).