Troubleshooting v2
Setup and Python detection in 2.0.4
Readiness and installation status appear within Setup. A running check should leave the interface responsive. After a failure, use Check again or View Logs. Correlated diagnostics record the selected Glyphs application, its bundle identifier and preference domain, Python candidates, native probe output and installation outcome. Optional packages retain their own release qualification requirements.
No Python framework path configured. means the older CLI could not find a saved selection; it does not establish that no Python module exists. Version 2.0.4 resolves the official default module when that preference is absent. If several Glyphs 4 copies appear, choose the one you use and inspect its detected Python. Copies with the same bundle identifier normally share a preference domain; beta identifiers can differ.
Install anyway bypasses a failed readiness check for component installation. It does not repair or install Glyphs Python. Use it only after reading the warning, then fix unavailable scripting through Glyphs' Plugin Manager and relaunch. Keep the diagnostic report when a usable Python still fails detection.
Start with get_status and the status in Edit → Glyphs MCP Server…. The server, bridge and external worker have separate availability: a reachable server does not by itself mean Glyphs is ready to edit.
| Symptom | Check or action |
|---|---|
| No server menu after installation | Confirm the component and selected Glyphs application, then restart Glyphs to load the new bundle. |
| Extension shows Ready but the client cannot connect | Use the server window's MCP URL, normally port 9680. |
Skill requests apiMajor == 2 | Identify its exact path and the selected connection. An obsolete private skill does not imply a stale lean server; see skill conflicts. |
| Client shows v1 tools | Check for an old server, duplicate connection or outdated agent package. Refresh the intended v2 connection. |
| Scripting preflight fails | Follow the Glyphs Python setup steps. Install the official module and relaunch Glyphs. Check the selected application and detected Python; choose a custom framework in Settings → Addons only if you intend to use one. Save work, quit all Glyphs 4 copies, and retry. |
| Worker unavailable | Open the Setup log window. The managed private runtime and CLI must match this Mac and the selected Glyphs application. |
| Port change rejected | Choose an available port other than the reserved bridge port, then update the client URL after applying it. |
| Git reference unavailable | Install or repair system Git, or use Last Saved or Font File. Verify repository, revision and font path. |
| No reference commands available | Open and save a font first. Unsaved fonts and no-font windows intentionally disable these commands. |
| Inspector does not appear | Confirm it is installed and enabled in View, and select an editable layer. Inspectors do not require an MCP client. |
Jobs and recovery
document_path_required or document_not_clean means the baseline is not
eligible for preparation. Do not call save_document merely to satisfy that
prerequisite; obtain authorization to save, or use a disposable saved copy. A
stale document or source error means the prepared job no longer matches the
font: discard the proposal and prepare again from the intended saved state.
For a timeout with uncertain execution, keep the job ID and call get_job. Do not submit a replacement mutation or restart the server to guess the outcome. A callback that was still pending is cancelled; one that had already started needs reconciliation.
A failed native write triggers target-level recovery. Read the error and recovery details. A failed job does not automatically prove complete restoration; incomplete recovery or a conflict with subsequent edits is reported explicitly. Preserve the evidence and use native Undo or Revert only after reviewing what would be lost.
Use discard_job to cancel preparation or reverse current affected targets of an applied job. Wait for a terminal result before starting another operation. Source files are saved only through Glyphs, not by applying a job.
Useful issue reports
Use Open Logs in the server window or Open Troubleshooting Logs in the Setup header. The dedicated desktop window combines installer events, card failures, recent server events and sidecar logs. Use Copy Redacted Diagnostic Report before sharing it. Include the product release/build, each component’s runtimeId and complete codeHash, interface/protocol revision, Glyphs version/build, architecture, reproduction steps, job ID, error/recovery details and a shareable disposable font if possible. Omit unrelated private data and inspect the redacted report before posting it.
Record idle and loaded responsiveness separately. The 200 ms HTTP probe threshold is diagnostic; investigate reproducible plugin stalls and distinguish modal waiting from native execution.
Submit an issue. The heart button also opens Documentation, GitHub Issues and Support links.