Troubleshooting

The interface opens, but chat does not work#

The Web interface, Kyalulu API and model provider are separate processes. An open interface does not prove the model is connected. Use connection diagnostics in Status to check the API, stored data, LE and model readiness.

1. Look for startup success or errors in the API terminal from the quickstart.
2. Check whether http://127.0.0.1:8000/api/models returns a model list.
3. Check provider status at http://127.0.0.1:8000/api/providers/health.
4. Choose Mock Echo to separate a check without an external model from real-model testing.

See local installation for API startup commands. Perform these checks in your own local environment.

Your model is missing from the list#

• LE: models served by LE appear as le:<id>. Check LE and its backend with /le status and /le models.
• YAML: restart the Kyalulu API after adding models/*.yaml. Match the provider model name to the actual ID served by the provider.
• LM Studio / Ollama: check server readiness, loaded models and the base URL. Do not append /chat/completions to the base URL.

A listed model is not necessarily loaded or ready to generate. See the model connection guide for examples.

Responses are slow or stop partway through#

Initial loading, model size, CPU offloading and conversation length affect latency. Distinguish time to the first visible text from time to completion.

Researcher Debug exposes settings, measurements and generation attempts. Avoid submitting the same input repeatedly while the result is unresolved. After a phone disconnects, wait for the generation ID and committed history to be reconciled.

A short benchmark from another setup is not a performance guarantee for your PC. Confirm provider loading state before trying a smaller model or changing the configuration.

Your phone cannot connect#

For the direct HTTPS PWA, check a device-trusted certificate, the exact HTTPS origin, an awake PC and device enrollment. Restarting the server invalidates enrollment, so you need to enroll again.

For Remote, check Host and Relay connectivity, QR expiry and the six-digit approval on the PC. Generate a fresh enrollment instead of reusing an old QR. A sleeping PC cannot generate replies even if the PWA opens.

Keep the direct HTTPS and Remote enrollment procedures separate.

Check conversion differences and report an issue#

Supported imports do not necessarily execute scripts or model-specific formatting. Check the preview and compatibility matrix for fields used during generation versus fields preserved only. Keep the original and compare it with the conversion.

If the issue persists, report reproduction steps, OS, version, provider and model ID, error text and expected behavior in GitHub Issues. Use a minimal example without API keys, enrollment QRs, private keys or personal conversations.