Troubleshooting

Installation & Startup

”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.

Python environment setup fails

Certum Draft ships with bundled Python packages (no pip install required), but the app needs to discover a system Python 3 interpreter the first time it runs.

1. Verify Python 3 is available on your machine — open Terminal and run python3 --version
2. If missing, install via the Mac App Store (“Xcode Command Line Tools”), the official python.org installer, or Homebrew (brew install python)
3. Quit Certum Draft and relaunch — it re-runs discovery and stores the path

Note

The bundled packages (docxtpl, openpyxl, jinja2, lxml, markupsafe) are pre-extracted and code-signed inside the app. You only need a working python3 binary — no virtualenv, no pip dependencies.

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. Open Console.app and filter for “Certum Draft”
2. Look for errors related to institution catalog loading
3. Restart Certum Draft
4. If the problem persists, reinstall Certum Draft — the catalog is bundled and a fresh install restores it

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.

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

PNM (Potential New Matter) Issues

New PNM 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.

Lead Inspector shows “This lead was updated elsewhere”

Stale-write detection has fired — someone else (or you on another machine) edited the Lead after you opened the Inspector. Click Refresh in the banner to load the latest version, then re-apply your changes.

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 PNM, 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 PNM 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

Files are locked by another user

When working on shared drives, another user may hold the matter lock.

1. Wait for them to finish (the banner shows their name and host)
2. Or ask them to close the matter to release the lock immediately
3. A lock that hasn’t been heartbeated in 15 minutes is treated as hard-stale and can be cleaned up automatically

”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).

Performance

App is slow to start

If you have many templates:

1. Open Settings → General → Templates
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.

• 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. Most paths in the app are debounced (auto-save 2.5s, computed-field updates 150ms, completion recalc 500ms), 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 — visible_when evaluation runs on every keystroke
• 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. Check the logs — Open Console.app and search for “Certum Draft”
2. Email support — [email protected] with:
   • A description of the problem
   • Steps you’ve tried
   • Any error messages
   • Your macOS version

Tip

Screenshots and log excerpts help diagnose problems faster.