# App Setup Troubleshooting Use this guide when Neotask is installed but setup is blocked by the app, gateway, voice, channels, automations, or app connections. --- ## First Triage Before diving into a specific app or workflow, identify which layer is failing: - desktop app install or first launch - gateway or local runtime - app connection or auth - channels and message delivery - automation and scheduled tasks - voice and microphone setup --- ## Desktop App Setup ### The app will not launch Check: 1. The installer finished successfully. 2. You are opening the installed app, not the disk image. 3. Your operating system did not block the app after download. If the app opens and then immediately fails, move to the gateway section below. ### The app opens, but onboarding is blocked Common causes: - license or sign-in issue - no active internet connection - a required browser auth step was never completed - the gateway did not finish starting Start with: 1. confirm your workspace access 2. confirm your license or plan state 3. confirm the gateway is healthy --- ## Gateway and Local Runtime ### The gateway failed to start This usually means the local runtime did not initialize correctly. 1. Fully quit and reopen Neotask once. 2. Open **Settings → Infrastructure → Connection**. 3. Check the **Local gateway** stage and use **Start** or **Restart** under **Gateway controls**. 4. Open **Settings → Infrastructure → Health** and click **Run check**. 5. Review **Settings → Advanced → System report** for the first live system check that needs attention. 6. Open **Settings → Advanced → Troubleshoot** and click **Check system** if the issue remains. 7. Read the result or open **Show technical output**. 8. Click **Apply repairs** when it becomes available. 9. Wait for the follow-up check before retrying setup. ![Gateway connection path and Gateway controls](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/docs/product/2026-08-13-r5/gateway-connection-1280.webp) The Health screen checks runtime responsiveness, workload, connected channels, and recent stability. ![Runtime Health with responsiveness, workload, channels, and stability checks](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/docs/product/2026-08-13-r5/gateway-health-full-1280.webp) When Connection and Health identify an installation problem, continue to the Doctor for the repair step. ![Troubleshoot settings used to check and repair the Gateway](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/docs/product/2026-08-13-r4/troubleshoot-system-check-1280.webp) ### The gateway disconnects after startup Possible causes: - a local runtime crash - a conflicting local service - security or permission issues on the device - stale local state after an update If tasks, voice, or app tools all stop at once, gateway health is the first thing to verify. 1. Refresh **Settings → Infrastructure → Connection**. 2. Run **Settings → Infrastructure → Health**. 3. Review **Settings → Advanced → System report**. 4. Use **Settings → Advanced → Troubleshoot** when a repair is needed. --- ## App Connection Problems Open **Apps** from the agent workspace and find the affected service. The catalog shows which apps are connected and which ones are still available to add. ![Connected and available apps in the agent workspace](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/landing/agents/2026-08-12-r1/apps-main-1280.webp) ### The app stays on Pending Possible causes: - the browser OAuth flow never finished - the provider callback never returned cleanly - the app is waiting on credentials or validation Fixes: 1. re-open the provider and finish setup again 2. verify the callback URL and scopes 3. confirm the app does not also require a custom instance URL Use the searchable picker only when the service has not been added yet. ![Searchable app picker for adding a service](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/landing/agents/2026-08-12-r1/app-picker-1280.webp) ### The app shows Error This usually means: - bad credentials - wrong provider app configuration - wrong instance URL - token refresh failure Go to [MCP Auth & OAuth Setup](./mcp-auth-oauth.md) and re-run the setup path for that provider. ### The app looks connected, but tasks still fail This often means the saved auth state and the runtime state disagree. Capture: - the provider name - whether the app says connected, expired, or error - whether the failure happens in the main agent, a tenant, or a company workflow - the exact task error --- ## Channels and Delivery ### A channel is linked, but messages do not arrive Check: 1. the channel account is still connected 2. the target account, room, or thread is correct 3. permissions or scopes were not removed 4. the channel is enabled for the right workspace or company flow ### Voice or phone delivery is not reaching the right place Check: 1. the saved phone number is correct 2. the route is tied to the right tenant or company 3. the caller is using the same recognized number expected by the workspace If member-only routing fails because the number is not recognized, support should fall back to guest support or manual verification rather than guessing. --- ## Automation and Scheduled Tasks ### A scheduled task did not run Check: 1. the schedule is still enabled 2. the task has the required apps connected 3. the task is not blocked on auth or approval 4. the delivery route still exists ### A task ran, but nothing was delivered Possible causes: - the task succeeded internally but had no valid delivery target - the target channel or route was disconnected - the task was blocked by a missing app auth state --- ## Voice and Microphone ### The microphone is not detected Check: 1. operating-system microphone permissions 2. the selected input device 3. whether another app is holding the microphone ### Voice activation does not trigger Check: 1. wake mode configuration 2. the selected shortcut or wake phrase 3. whether microphone permissions were granted --- ## When Support Should Escalate Escalate instead of repeating generic troubleshooting when: - the same provider fails after a correct reconnect - billing is active but account access is still broken - a task appears ready but company execution still reports missing auth - member caller recognition is clearly wrong for a saved employee or member route - the app state and the runtime state contradict each other Related guides: - [Support & Routing](./support.md) - [Account Access](./account-access.md) - [MCP Auth & OAuth Setup](./mcp-auth-oauth.md) - [Troubleshooting](./troubleshooting.md)