Symptom-first diagnosis

Find the first boundary that failed.

Start with the Check button, preserve local data before resetting anything, and distinguish a provider failure from IdeaForge's deliberate checklist fallback. Most local-model problems are one of four boundaries: process, address, CORS, or browser permission.

The short decision tree

1. Does the page boot? If not, use a real http:// or https:// origin, check the browser console for a missing static file or CSP violation, and use the page-startup branch.
2. Does Check the key or Check the connection pass? If not, do not start an interview yet. Follow the hosted-provider or local-provider branch.
3. Does the turnline say built-in checklist? The app is alive, but the model call or model output failed for that turn. Follow checklist fallback.
4. Is the problem limited to saving, voice, Docker, or validation? Skip directly to the matching branch below; those subsystems have separate permissions and failure modes.

The page does not load or stays blank

1. Confirm the URL is an origin

file:// is unsupported. From a clone, run:

npm run serve
# open http://127.0.0.1:8765

If another static server is used, verify that it serves JavaScript modules with normal browser-readable MIME types and preserves the repository's relative paths.

2. Check the first failed resource

Open developer tools, reload, and inspect Console and Network. A missing module, blocked stylesheet, wrong subpath, or CSP violation is more useful than a later cascade of undefined errors. The application must work both at an origin root and under a Pages-style subpath; do not rewrite its relative URLs to root absolute paths.

3. Refresh a stale service worker without deleting sessions

1. Reload once, wait for the service worker update, then reload again.
2. Close other tabs for the same origin if an old page remains open.
3. If the shell is still stale, remove the IdeaForge service worker and its Cache Storage entry in developer tools, then reload.
4. Leave IndexedDB alone unless you have already backed up the library. Cache Storage and IndexedDB are different stores.

The service worker never handles the guide/ path, so a stale guide page is an ordinary HTTP or browser-cache issue rather than the app-shell cache.

A hosted key check fails

1. Confirm the provider selection matches the key issuer. A key from one provider cannot be used through another provider's preset.
2. Create a new scoped key in the provider console. Paste it directly, avoid copying surrounding quotes, and press Check the key again.
3. Read the error class. Authentication needs a key change; rate limiting needs time or a provider-side limit change; overload is usually transient; a deadline suggests an unreachable or stalled service; a bad response points to incompatible model output.
4. Check browser interference. A privacy extension, enterprise filter, VPN, DNS filter, or network proxy can block the provider origin before the browser exposes an HTTP response.
5. Use the provider status and account pages. Confirm the project is active and the key has permission and remaining quota. Do not paste the key into an issue or screenshot.

A local connection check fails

Work through these in order. Each step proves a different boundary.

1. Prove the server process answers on the host

For Ollama:

curl http://127.0.0.1:11434/api/version
curl http://127.0.0.1:11434/v1/models

For LM Studio's default address:

curl http://127.0.0.1:1234/v1/models

If the direct request fails, fix or start the model server before changing IdeaForge. If it answers but lists no models, pull or load one. In Windows PowerShell, use curl.exe if curl is mapped to Invoke-WebRequest.

2. Use the API root, not an individual endpoint

The server address normally ends in /v1. IdeaForge appends /models and /chat/completions. Do not paste the full /chat/completions URL.

3. Use explicit IPv4 loopback

Try 127.0.0.1 instead of localhost. Do not use 0.0.0.0, a LAN address, or bracketed [::1]. If localhost and 127.0.0.1 show different model lists, two local servers are answering on different address families. Choose one explicitly.

4. If the app is hosted, fix CORS

• Ollama: set OLLAMA_ORIGINS to the app's exact origin and restart the Ollama process or service.
• LM Studio: enable CORS in the server settings, or start the server with its CORS option.
• A page origin contains the scheme and host, not the path. For the public Pages deployment, allow https://jaypetez.github.io, not the /ideaforge/ path.

5. If using Chrome from a hosted page, allow Local Network Access

Press Check the connection and accept Chrome's site permission. If it was denied earlier, reset the site's Local Network Access permission in browser settings, reload, and press Check again. A CORS fix cannot substitute for this permission, and the permission cannot substitute for CORS; both must pass.

6. If using Safari from a hosted page, move the app local

Serve IdeaForge at http://127.0.0.1:8765. The shipped app does not support the hosted-HTTPS to local-HTTP path in Safari.

7. If using a phone, stop using the computer's localhost

On a phone, localhost means the phone. IdeaForge intentionally refuses a computer's 192.168.x.x address. Use a hosted model on the phone or run the app on the computer with the model.

8. If the list fails but the server is compatible, type the model

Both model fields are editable inputs, not locked selects, for every provider. A custom server may omit /models yet still implement chat completions, and a hosted catalogue may not list a model your account can actually reach. Type the exact identifier and start only after proving that the chat endpoint answers.

See CORS, Local Network Access, and Safari for the full browser matrix.

Docker does not start or is unexpectedly slow

Useful first commands:

docker compose -f docker/compose.yml ps
docker compose -f docker/compose.yml logs --tail 100 ollama
docker compose -f docker/compose.yml exec ollama ollama list
docker inspect <ollama-container> --format '{{json .HostConfig.DeviceRequests}}'

The interview uses the built-in checklist

This is a degraded but intentional path, not data loss. The seed question never needs a model. For later turns, IdeaForge falls back when the provider is absent, unreachable, times out, returns unusable JSON, or produces a question that remains repetitive or compound after one regeneration.

1. Read the visible error beside the turn; it names the provider or response failure.
2. Return to Settings and run Check the key or Check the connection.
3. For a local model, inspect the browser console for [ideaforge] warnings. They distinguish absorbed model-shape quirks from a turn that had to fall back.
4. If a small local model trips a question-quality guard once, retry the validation run before treating it as an application regression. Repeated bank turns with network errors are a server or browser problem, not model luck.

The completed screen records whether any question came from the checklist. A successful-looking export alone is not proof that the provider worked.

The wrap-up fails

The synthesis call is larger than an ordinary turn because it uses the interview transcript to produce the title, refined prompt, assumptions, and open questions. Local models that handled short turn prompts can fail here because of context, memory, output length, or model-shape limits.

• Keep or download the document already shown. The transcript, coverage, and open questions remain; the refined prompt is marked as not generated.
• Check that the model remains loaded and has enough memory for the larger context.
• Run npm run validate:local to exercise the same final synthesis.
• Reopen the idea and ask for more only after the provider is healthy; reopening continues from the saved session rather than reconstructing it from the export.

A session is not saved or disappears

IdeaForge surfaces IndexedDB failures with a message telling you to export before closing the tab. Common causes are private browsing restrictions, disabled site storage, quota pressure, browser eviction, or a database upgrade blocked by another open tab.

1. Keep the tab open and export the current idea immediately.
2. Close other IdeaForge tabs, then reload and retry.
3. Check that browser storage is allowed for the exact origin you are using.
4. Install the app if practical, then start or import again so persistence is requested.
5. Back up the whole Ideas library before clearing any site data.

If a saved key disappears while sessions remain, the wrapping key may have been evicted independently of the ciphertext. IdeaForge deletes the now-undecryptable credential payload and asks you to paste the key again rather than looping forever.

Voice or dictation is unavailable

1. Confirm microphone permission for the exact app origin.
2. If the mic button is absent, read the setup message. It distinguishes the two causes that look identical from inside the page: a microphone blocked for the site, which you fix in the browser's site settings and then start an interview again, and a recogniser that exists but fails its proof-of-life check, which you work around with a transcription key.
3. In an installed iPhone app, Edge, or Firefox, configure Groq or OpenAI transcription instead of relying on browser recognition.
4. If inference and transcription use different providers, paste the separate transcription key. If both use Groq or both use OpenAI, the inference key is reused automatically.
5. Test a short recording. An empty or extremely short capture is discarded rather than sent for transcription.
6. If a dictated answer repeats its own opening words, such as I I want I want to…, the page is running a copy of the app from before v0.6.1. Reload it twice: the service worker fetches the new version on the first load and uses it on the second. If it persists, report the browser, the device, and whether a Bluetooth headset or car was the microphone.

See Mobile and voice for hands-free commands, trigger-word rules, and platform-specific setup.

The real-model validator fails

Full validator setup and environment controls are in Validate a real model.

Report a reproducible problem

For an ordinary bug, open a GitHub issue with:

• the exact app origin and whether it was hosted, local, or containerised;
• browser and operating-system versions;
• the selected provider, both model choices, and for local models the base URL;
• the complete visible error and relevant console warning;
• whether Check the key or Check the connection passed;
• the smallest safe reproduction, with all API keys and sensitive transcript text removed.

Report suspected credential exfiltration, script execution, or cross-origin storage access through private vulnerability reporting, not a public issue.

Implementation references

Provider error classes and retry policy are in src/providers/errors.js. Local diagnostics and request deadlines are in src/providers/http.js and src/providers/openaiCompat.js. The fallback path is coordinated by src/runtime/turn.js.

Storage errors and recovery are in src/store/db.js and src/store/secrets.js. Docker diagnostics come from docker/compose.yml and tools/validate-local.mjs.