Troubleshooting

Installation & Startup

No update is offered

Certum Draft requires macOS 27. A Mac still on macOS 26 keeps 0.9.373 and is not offered any later version until it upgrades; the Updates pane says “Up to date” because, for that Mac, it is.

”Certum Draft is damaged and can’t be opened”

This appears the first time you run Certum Draft after downloading a fresh DMG when macOS hasn’t yet seen the developer signature.

1. Right-click the app in Finder
2. Select Open from the context menu
3. Click Open in the dialog that appears

After the first launch, normal double-click works.

App won’t launch after update

A Sparkle auto-update can occasionally land a half-installed bundle if interrupted (network blip, system sleep at the wrong moment).

1. Open Finder → Applications
2. Move Certum Draft to the Bin
3. Download a fresh copy from certum.serkowski.net
4. Install again

Your settings, license, and matters are preserved.

Document engine setup fails

Certum Draft’s document engine — including its own Python runtime — is signed and bundled inside the app. There is no system Python to install and nothing to configure by hand.

If the one-time check fails, the dashboard shows a “Document engine unavailable” banner:

1. Click Retry Setup… in the banner to reopen the setup check
2. In the setup window, click Reset & Retry
3. If the check keeps failing, download a fresh copy from certum.serkowski.net and reinstall — reinstalling restores the bundled engine

Note

You never need to install Python from python.org, the Mac App Store, or Homebrew — the app doesn’t use your Mac’s Python at all. If an older version’s error message told you to, ignore it.

”Python engine failed” or an engine error on generate

When the engine itself fails on a render — a bad input, a missing temporary file — the error banner now leads with the engine’s own message; the traceback sits behind Technical details for whoever maintains your templates. A message naming a field (“missing field client.surname”) is a template or data problem, not an installation one: fill the field or fix the precedent and generate again.

License Issues

”Invalid license key”

Check that:

• You copied the entire key (no leading/trailing whitespace)
• The email matches the one your license was issued to
• The key hasn’t been previously revoked

Need a new license key

Email [email protected] with the email address the license was issued to.

Templates

Template doesn’t appear in the picker

1. Open Settings → Paths and verify Templates Root points at the right folder
2. Confirm the template folder contains a valid matter.json file
3. Quit and relaunch Certum Draft to refresh the cache

”No templates found”

Your Templates Root is empty or misconfigured.

1. Open Settings → Paths
2. Click Choose… next to Templates Root
3. Select the folder containing your template subfolders

Template validation shows errors

The startup validator catches Jinja2 syntax errors. To re-run validation manually, open the Template Manager from any matter type’s editor.

Common causes:

• A {{ field }} placeholder using a key that doesn’t exist in matter.json
• Mismatched {% if %} ... {% endif %} blocks
• A matter.json with invalid JSON (use a linter if unsure)

“No Template Available”

The template can’t be read from the templates folder.

Causes:

• Dropbox Smart Sync has evicted the template files (they show as “online only”)
• The network drive containing templates is offline
• The template folder was moved, renamed, or unshared

1. Open Finder and navigate to your Templates folder
2. Check that the template subfolder and its matter.json are fully downloaded (not cloud-only placeholders)
3. If using Dropbox, right-click the template folder and select Make available offline
4. Restart Certum Draft to refresh the template cache

Institution search returns no results

The bundled institution catalog ships inside the app and is loaded at launch. If search is empty:

1. Restart Certum Draft
2. If the problem persists, reinstall Certum Draft — the catalog is bundled and a fresh install restores it
3. Still stuck? Open Settings → Diagnostics, click Export Diagnostics, and email the support bundle to [email protected]

Template changes not appearing

The template cache may be serving a stale version.

1. Ensure the updated matter.json is fully synced to disk (check Dropbox sync status)
2. Restart Certum Draft to force a cache refresh
3. Verify the changes by opening a matter of that type

Compliance tab not showing

The Compliance/AML tab only appears on matter types that include a "Compliance" stage in their workflow_stages array.

Templates with Compliance by default: Purchase of Land, Sale of Land, Estates, Lease - Landlord, Lease - Tenant.

Templates without Compliance: Wills, Advice, Reverse Mortgage Advice.

To add a Compliance stage to a template that lacks one, add "Compliance" to the workflow_stages array in matter.json and assign blocks to it with "workflow_stage": "Compliance".

Document Generation

Placeholder shows [MISSING: field_name]

The template references a field with no value.

Causes:

• The field wasn’t filled in when the matter was created
• The field name in the .docx template doesn’t match matter.json
• The field uses a legacy PascalCase name (e.g., Client_Surname) instead of dot-notation (client.surname)

Solution:

1. Re-run New Document from the matter — the wizard’s “Missing Fields” step prompts you for any required value that isn’t set
2. Or open the matter, fill in the missing field manually, and regenerate

Tip

Certum Draft never blocks matter creation on required fields — empty beats bogus. The Missing Fields wizard step at document-generation time is where required-ness is enforced.

”Rendered in fallback mode, do not send”

The precedent could not be parsed — a stray % }, a mismatched {% if %}, an unknown filter — so the engine rendered what it could without the template logic. The document is marked fallback, never complete; every broken control tag appears in it as a visible [TEMPLATE ERROR: …] marker, the wizard’s completion screen lists the warning first in red, and institution letters, settlement sets and wills show the same red feedback instead of a “Generated” toast. Don’t send it. Fix the precedent (the marker names the tag) and re-run template validation, which now reports unknown filters and unreadable .docx files as errors rather than passing them.

Word says the document has unreadable content

A render inherited a defect from its precedent: a .docx saved by some namespace-pruning tools lists an XML prefix it no longer declares, and Word offers to recover it as “Document 1”. Since 0.9.385 the renderer repairs that list on every render, so a current build cannot produce the prompt; if you still see it, the document was rendered by an older version — regenerate it. Open the precedent in Word and re-save it to repair the source.

Letters printed the word “None”

A cleared date or amount with a | date or | currency filter used to render as “None” (“died on None”). Current builds render it blank; regenerate the document, and fill the field if it should have had a value.

Documents don’t generate

Check that:

• The matter folder contains a {matterNumber}-matter.json file
• You have write permission to the matter folder
• The document templates exist in the template’s precedents/ folder

Wrong information in document

1. Open the matter and edit the field on the Details tab
2. Regenerate the document

Note

Editing matter details doesn’t update documents that have already been generated — you need to regenerate them.

Address shows [DRIFT: …]

A verified address has drifted from its stored fingerprint — the canonical hash that was stamped on confirmation no longer matches the current value. Open the matter, click the address row, and re-confirm via the AddressField (with or without a MapKit suggestion). The next regeneration emits the clean address.

Address Verification

MapKit suggestions don’t appear

• Check your internet connection — MapKit needs network access to return results
• Ensure macOS has granted Location access if the suggestion list is empty (the app doesn’t require Location for typing, but coarse region narrowing improves matches)
• Try typing a more specific query — MapKit needs at least a few characters

”Pick timed out”

The MapKit resolve takes longer than 10 seconds. Almost always a transient network issue. The structured fields aren’t touched — the lawyer can type them manually. The verification status falls back to manual rather than mapkit.

Address won’t stay verified

If the Confirm button reverts on the next reopen:

• Check the matter saved properly (the auto-save indicator should say “Saved”)
• If the matter sits on a shared Dropbox/network drive, ensure another user isn’t editing it concurrently — only one user can hold the lock at a time

Leads Issues

New Lead button doesn’t appear on the dashboard

The button is gated on two conditions:

• Your Notion Leads database must be configured (Settings → Notion → Leads → Find or Create Leads Database…)
• Your Matters Root must be set (Settings → Paths)

If both are configured and the button still doesn’t appear, restart Certum Draft.

”Configured database isn’t reachable right now”

Your Leads database ID is stored, but the integration can’t currently see it. Causes:

• Transient network blip
• The database was unshared from the integration in Notion
• Notion integration permissions are still propagating

Click Retry in Settings → Notion → Leads. Certum Draft preserves the stored ID until you explicitly adopt a different database or create a new one.

Conversion stuck in “needs repair”

The Lead → Matter conversion crashed or was interrupted partway through. The Inspector shows a Repair banner in the conversion-state row.

1. Click Repair in the banner
2. The repair flow checks whether the matter folder was created and either links it back to the Lead or rolls forward to a clean conversion
3. If the matter folder was never created, the journal resets so you can convert again

Folders without leads

For users with existing matter folders that pre-date the Leads feature, the Reconciliation view (open from the Leads list) scans Matters Root for matter folders that have no corresponding Lead in Notion and offers to backfill a Lead for each one. Useful when adopting the Leads workflow on an existing practice.

Finder Integration

Services options don’t appear in the right-click menu

1. Open Certum Draft at least once so the Services are registered with macOS
2. Hold ⌥ (Option)
3. Right-click Finder in the Dock and select Relaunch
4. Try right-clicking a folder again

”Generate Documents” is greyed out

The selected folder isn’t a recognised matter folder. The folder must contain a *-matter.json file (or the legacy matter.json).

Shortcut ⌘⌥G doesn’t fire

Service shortcuts are user-configurable in System Settings → Keyboard → Keyboard Shortcuts → Services. macOS sometimes drops conflicting shortcuts on update — re-enable them in System Settings.

File & Folder Issues

Matter folder won’t create

Check that:

• You have write permission to the Matters Root folder
• The destination isn’t full or mounted read-only
• A folder with the same name doesn’t already exist (the folder-naming template should be unique enough)

Can’t save matter details

1. Check the matter folder isn’t locked or read-only
2. Confirm no other app is holding the file open
3. If on a shared drive, check the matter-lock banner — another user may have it open

”This Matter Changed Elsewhere”

Another window, another Mac or the automation API wrote the matter file after this window last read it, so the save was refused rather than overwriting their change. The banner has no Retry, because a retry could never succeed. Choose:

• Reload and Re-apply My N Changes — loads the newer version, puts your unsaved field edits back on top of it and saves. A follow-up banner lists any field that was changed in both places, with the other value, so you can settle it. Institution, destination, checklist, critical-date, proposal and invoice-draft edits are not re-applied — the banner names them before you choose.
• Copy My Unsaved Changes — puts your edits on the clipboard first, if you’d rather compare by hand.

A Dropbox conflicted copy sits beside the matter file

When a matter opens with a Dropbox “conflicted copy” of its matter file in the folder, a banner warns that changes made on another Mac may exist only in the copy; Show in Finder selects both files. Compare them (the conflicted copy is plain JSON) and, once nothing in it is needed, move it out of the folder — Certum never deletes it for you.

The matter opened read-only

Another Mac holds the editing lock: the banner shows who and how old the lock is.

1. Wait for them to finish, or ask them to close the matter — closing releases the lock at once
2. A lock whose Mac went to sleep or lost its connection goes stale on its own: it is flagged “may be stale” after 5 minutes and can be cleaned up after 15
3. Take Over (after a confirmation) acquires the lock anyway; the other Mac is told and its window switches to read-only

Locks record the Mac’s hardware identifier, so two Macs with the same computer name can’t delete each other’s lock. A lock that an older version kept renewing after the matter was closed (“being edited” all night) was fixed in 0.9.379; update that Mac.

”Connected but no token” warning

This appears when Notion is partially configured: database IDs are saved, but no integration token is in Keychain (or vice versa). Open Settings → Notion and complete the missing half (Save Token, or Save Database IDs).

Notion and Tasks

Is Notion working?

Settings → Notion → Connection has a Status line: whether Notion is answering, a rejected token, a request it refused, a list cut short at Notion’s 1,000-row cap, and any client update still waiting to reach Notion (with Retry and Discard). When something is wrong the menu-bar item carries one line about it. A matter whose Tasks or Firm list says the firm-wide fetch failed is reporting the same outage, not an empty list.

Completion notices don’t reach the person who assigned the task

The notice is a Notion comment and needs the integration’s Insert comments capability, which a token created for reads and writes alone doesn’t have. Turn it on at Notion’s integrations page; until then Settings → Notion says “Completion notices aren’t reaching Notion”. Task reads, ticks and captures are unaffected. The same capability covers the team comment on a new matter.

A task shows “Not sent” or “Couldn’t complete …”

A capture that Notion refused outright is Not sent, in red, with Retry and Discard; one still retrying after an outage shows amber under “Sending” and goes on its own once Notion is back. A tick, date, reassignment or rename Notion refused puts the row back and says why above the foot of the Tasks page, with Retry where the write can be replayed. Nothing was written in either case.

A linked client’s name won’t change

Notion owns a linked client’s name; Certum takes Notion’s on every open. Edit it on the client page in Notion. See Notion Integration.

Automation

”Connection refused” while Certum is running

Something else held the automation socket when the app started — most often an older copy of the app or a test run — and the app refused to take it over. It retries on its own (every 5 s, doubling to every 5 minutes) while the setting is on; turning Enable local automation API off and on in Settings → Automation forces it at once.

Claude has no Certum tools

A chat started before Certum was running sees the bridge’s cached tool list; the tools work once the app answers, and the host is told to re-list them. If the chat still shows none, restart it. A host whose MCP configuration points at an old copy of the bridge shows as out of date in Settings → Automation → MCP bridges this session — point it at scripts/certum-mcp itself.

An agent’s proposal was refused with a field name

matter.propose_fields refuses a batch whose key is one or two letters from a field in the matter’s pack (a likely typo) and names that field. Fix the key and send the batch again. A key the pack doesn’t declare at all is accepted but flagged “not in pack” in the review sheet.

Appearance

Horace doesn’t move

With Reduce Motion on in System Settings → Accessibility, Horace holds a still pose: a tap, a cleared docket or a staged update puts a line in his bubble and nothing animates. Turn Reduce Motion off to get the acts back.

Performance

App is slow to start

If you have many templates:

1. Open Settings → Paths
2. Turn off Validate templates on startup
3. Relaunch

You can still validate on demand from the Template Manager.

Document generation is slow

Large templates or large batches take longer. The wizard renders the whole set in one engine run and shows “Rendering X (3 of 12)…” as it goes; Cancel stops the batch and keeps what was already written.

• Generate fewer documents at once
• Close other applications to free RAM (lxml uses considerable memory for big workbooks)

Form typing feels laggy on huge templates

Templates with 20+ blocks and 100+ fields can cause typing lag. Computed fields, visibility and completion recalculate together 150 ms after you stop typing, settlement and estate figures once per settled change, and auto-save 2.5 s later, but extreme cases can still feel sluggish. If you’re a template author hitting this:

• Look for blocks with very long lists of conditionally-visible fields and deep computed-field chains
• Consider splitting one mega-template into per-stage sub-templates if it grows beyond ~150 fields

Getting More Help

If you can’t resolve an issue:

1. Export a support bundle — open Settings → Diagnostics and click Export Diagnostics. This gathers recent logs and system diagnostic reports into one file you can attach to an email. The bundle can contain client names, matter numbers, and file paths, so treat it as client-confidential.
2. Email support — [email protected] with:
   • A description of the problem
   • Steps you’ve tried
   • Any error messages
   • Your macOS version
   • The support bundle, if you exported one

Tip

Screenshots and a support bundle help diagnose problems faster than anything else.