Troubleshooting

Use this page to fix common problems with search, recording, local tools, and building Lumen. Start with the message Lumen shows and the folders or sources you selected. Lumen has no online fallback, so a missing tool, missing access, or unsupported file needs a local fix.

Search doesn't find a file#

This usually happens when the file is outside your chosen folders, the index is out of date, the file was skipped, or the file type needs the search package.

1. Open Settings → Search and check that the file is inside an available chosen folder.
2. If you changed files, choose Refresh index. With the search package, Lumen also watches chosen folders when automatic refresh is turned on in Settings.
3. Review the indexing issues shown in Search. Check supported formats and limits.
4. Search for an exact name or number, or put a short phrase in quotation marks.
5. If the file is stored only in iCloud, download it in Finder, then try again.
6. For a scanned PDF, use a build with the search package and let its OCR and indexing pass finish.

Note: File search covers your chosen folders only. To search saved transcripts and notes, use Search meetings in Meetings.

Search matches exact words but not related ideas#

Semantic search needs local vectors. Until they're ready, Lumen matches exact words.

1. Let indexing finish. Progress and the current file appear in Search.
2. Check which build you're using. Without the search package, file search uses text and PDF keywords, plus the older optional text and image adapter.

Indexing seems stuck on one file#

The first time macOS sets up OCR, it can be slow. In one cold synthetic run, OCR took about 66 seconds; running it again took under a second.

1. Wait for the current file to finish. Lumen keeps it visible while it works.
2. If you need to stop, choose Pause or Cancel.

Each worker batch has a 15-minute deadline. Completed work stays saved, and Refresh index retries files that failed.

Indexing is paused#

Lumen pauses indexing at safe points during meetings, note processing, and memory pressure.

1. Let the meeting or note processing finish, or free up memory.
2. If you paused indexing yourself, choose Resume.

Cancel stops the current run and keeps the previous index.

A file was skipped or shows an error#

1. In Search, review the error for that file.
2. Fix the cause using the following table.
3. Choose Retry or Refresh index.

A folder is unavailable or asks to be chosen again#

Moving a folder, restoring a backup, or rebuilding an ad-hoc-signed app can invalidate folder access. Lumen withholds results from an unavailable folder until access returns.

1. Open Settings → Search.
2. Choose Choose again… and select the folder.

You don't need to delete the index to fix this.

Meeting search doesn't find a meeting#

Search meetings searches saved transcripts, titles, rough notes, and generated notes.

1. Check that the meeting isn't still recording. Active recordings and sample meetings are excluded.
2. For an imported recording, wait until preparation finishes. The meeting joins meeting search afterward.
3. For a search by meaning rather than exact words, wait for local meeting vectors to finish preparing.

A meeting has no transcript or summary#

This happens when local tools aren't ready, the build doesn't include the local AI bundle, or processing failed.

1. Open Settings → Meetings → Local models and check the readiness state. Bundled models are verified when Lumen starts, and Local models ready means they passed.
2. If you use a base build, it doesn't include the local AI bundle. Developers can import a verified package through Settings → Meetings → Local models → Details → Choose local tools…. The package must provide both transcribe and summarize operations; a model weight file alone can't supply them. See the tool contract.
3. Choose Show saved audio to check the saved input for the meeting.
4. Choose Prepare notes again.

Note: In a build without bundled models, Get started downloads them once from Hugging Face; check progress in Settings → General → AI models. The sample meeting contains example content only.

Recording fails or call audio is missing#

Microphone access and call-audio access are separate macOS permissions.

1. Check which sources you selected, and read Lumen's warning.
2. In macOS, open System Settings → Privacy & Security. Review the Microphone and Screen/System Audio Recording entries. Their labels vary by macOS version.
3. If macOS asks you to reopen Lumen, reopen it.
4. Start a short test recording.

If call-audio access is denied, Lumen can continue with microphone-only recording and shows a warning. Microphone-only audio may not include other participants. A running timer doesn't confirm that you'll get a transcript or a usable audio track.

Note: Live capture across macOS permission states, call routing, and real hardware hasn't been validated yet. See remaining validation.

Microphone or screen/audio access asks again after approval#

macOS ties saved permissions to an app's code-signing requirement. Earlier versions of the build script ad-hoc signed every changed build, so an updated app could fail that check even while System Settings still showed Lumen as allowed. The build script now signs with your Apple application signing certificate when one is available. On a Mac without a certificate, it still uses ad-hoc signing and shows a warning.

1. Build with an Apple application signing certificate, and keep using the same certificate and app bundle. See development signing.
2. After you switch from ad-hoc signing, macOS may ask the newly signed app to access Lumen's existing saved data before its window opens. Respond to that system prompt.
3. Approve microphone and screen/audio access once for the certificate-signed app. If macOS asks you to restart the app, reopen it.

Later builds signed with the same certificate keep these permissions. If the prompts come back without a rebuild, write down the exact permission and when it appeared. Signing checks alone don't validate how macOS handles live capture.

Important: Don't reset all privacy permissions, remove saved recordings, or turn off macOS security features to fix this.

Lumen closed before a meeting finished#

1. Reopen Lumen, select the meeting, and read its interrupted-session notice.
2. Choose Show saved audio and keep that folder.
3. Prepare the required local tools.
4. Choose Prepare notes again.

Lumen recovers finalized audio chunks from a journal where available. After an abrupt interruption, the last unfinalized part of the recording may not be recoverable.

Important: Don't remove Lumen's application data folder while you're trying to recover a meeting.

Audio remains after you turn off audio retention#

Keep original audio applies to new meetings. When it's off, Lumen deletes audio only after transcription, note generation, and durable saves succeed.

Lumen keeps the audio for retry when tools are missing, processing fails or is cancelled, or the meeting was interrupted. To learn more, see How audio retention works.

A tool package fails verification or processing#

Lumen rejects path traversal and symlinks that point outside the package. A runtime must work with networking blocked and with explicit model paths.

1. Check these parts of the package:
   • lumen-tools.json and its schema version
   • The pinned model identity and revision
   • Relative paths and executable permission
   • SHA-256 values
   • Declared operations
2. If verification fails, get or rebuild the expected package from a trusted source. Don't bypass checksum validation to force an import.
3. For response-shape failures, compare the output with the Codable types linked from local tools.
4. If processing fails, read the runtime error that Lumen shows and check available memory. Long transcripts are split into bounded batches, and failed processing keeps the input for retry.

The app will not build or open#

1. Run swift --version and confirm that it reports Swift 6 or later.
2. Run xcode-select -p and confirm that it points to a toolchain with the macOS SDK.
3. From the source folder, run ./scripts/build-app.sh release. If it fails, read the first build or signing error.
4. Open build/Lumen.app only after the script succeeds.

This is a signed local development build, not a notarized public installer. Don't disable Gatekeeper or remove quarantine to work around a problem. If you received a binary from somewhere else, build from verified source or wait for an official release channel.

Frequently asked questions#

Report a reproducible problem#

When a public repository is available, use its bug report template. Include:

• Your macOS version, Mac chip, and RAM
• Your toolchain version, for build failures
• The exact steps, what you expected, and what happened
• Whether you used the signed bundle

Use Evaluation/Fixtures or a small synthetic reproduction when you can. For model issues, include the artifact identity, revision, and sanitized errors. Don't include model weights or private recordings. See contributing and security reporting.

What's next#

• Search files
• Meetings
• Privacy and permissions