Troubleshooting

What this accomplishes

Common Code issues — diagnostics, logs, and where to get help.

When something breaks in Code — editor, language server, agent, sub-agents, search, git, or memory — start with diagnostics and the support channels below.

Current availability

This page documents behaviour verified in Miton development builds. Miton is still pre-release and is not publicly downloadable; invited beta users will receive a signed desktop build with automatic updates.

Before you start

• A Miton development build and an active project containing source code.
• A connected model. Trust the project before allowing file, terminal or Git actions.

Start with the evidence Miton already exposes

Open Settings → Privacy & diagnostics, then record the application version, operating system, active project, selected model and exact failing action. For Code failures, also record the current branch, dirty files and language-server state. Do not copy provider keys, access tokens or document contents into a bug report.

Common issues

The agent is not finding the code I expect

The agent is using the code search. The code search is indexed per project. The user can:

• Check the file isn’t excluded by .gitignore — code search follows it, and there’s no separate search-only ignore file.
• Give the index a moment after a large change lands; it updates in real time but a big burst of file changes takes longer to settle.

The language server is not responding

The language server is started by the editor when the editor detects a file with a known language. The user can:

• Check the language server status in the diagnostic surface. The status should be “running” for the current file’s language. If the status is “not found”, the language server is not on PATH; the user can install the language server or configure the language-server binary path in the settings surface.
• Restart the language server from the diagnostic surface.

The sub-agent is stuck

A write-capable sub-agent may be running in an isolated worktree. It can be stuck on a task that is taking too long, or on a permission gate the user hasn’t answered. The user can:

• Check the Specialists dashboard (see transparency and approvals). It shows the run’s status, tool calls, and cost.
• Cancel the run from the dashboard. There’s no pause/resume for a running sub-agent — cancelling stops it; an isolated worktree it was using can then be discarded from the review dialog.

The memory is making bad suggestions

The memory is a learning signal, not a black box. The user can:

• Open the memory surface in the settings panel. The surface shows the rules, the patterns, and the confidence scores.
• Identify the rule or pattern that is causing the bad suggestion. The rule is marked as the rule that was applied in the chat metadata.
• Edit the rule, mark the pattern as ignored, or reset the memory.

The drift detection is flagging false positives

Drift alerts (in the Project area’s Drift tab — see Blueprints and milestones) can be dismissed individually. If the blueprint itself is stale, refreshing it against the current codebase clears alerts that were only measuring against out-of-date component data.

The convention memory is suggesting code the user does not want

The convention memory is a learning signal. The user can:

• Open the memory surface in the settings panel. The surface shows the rules, the patterns, and the confidence scores.
• Identify the rule that is causing the bad suggestion. The rule is marked as the rule that was applied in the chat metadata.
• Edit the rule, mark the pattern as ignored, or reset the memory.

The file watcher is not picking up changes

• Check that the file isn’t excluded by .gitignore — the file watcher follows it.
• Reopening the project re-establishes the watcher if a change was made while the app wasn’t running or the project was closed.

The support channels

Report a bug and Send feedback, both in Settings, each open a pre-filled GitHub issue on foundryseven/miton in your browser — no source code or conversation content is attached automatically. Settings → Privacy & diagnostics can also copy a diagnostics JSON (version, build, OS, crash-log summary) to paste into the issue yourself.

The bug-report flow

1. Reproduce the bug.
2. Open Settings → Privacy & diagnostics and copy the diagnostics JSON.
3. Open Report a bug in Settings. It opens a GitHub issue with your description pre-filled — add the diagnostics JSON, and the steps to reproduce, expected behaviour, and actual behaviour.
4. Submit the issue on GitHub.

Never paste provider keys, access tokens, or document contents into an issue.

What success looks like

The diagnostic surface is the entry point for debugging: Settings → Privacy & diagnostics shows the application version, OS, and a crash-log summary you can copy into a bug report.

Report a bug and Send feedback are the support channels, and both go to a GitHub issue on foundryseven/miton — no source code or conversation content attached automatically.

Common failures and recovery

• Confirm the correct project and branch are active.
• Check the model connection and the permission request shown in Chat.
• Keep the exact error before retrying; use Code troubleshooting when the failure persists.

Related next action

Return to the Code overview and resume from the last verified project state.