Troubleshooting and FAQ

Now we'll close with the things that go wrong and the questions people ask. Each problem below gives what you see, why it happens, and what to do. Almost every error in Cocoa appears in the same place — the detail area, under the heading Could Not Open That Folder — so that heading is where to look first.

The notes folder

Could Not Open That Folder ①, with a message under it ②, and the buttons Create My Notes Folder and Choose Another Folder… ③.

• Why: the folder chosen at setup has moved, been renamed, is on a disk that is not mounted, or a file operation was refused. The message under the title is the system's own reason.
• What to do: if the folder still exists, Choose Another Folder… and pick it. If not, Create My Notes Folder makes a fresh one — your old notes are still wherever the old folder went, and File › Import… › Folder of Markdown brings them in.

"…is not a folder." — the chosen path is a file. Choose the folder that contains your notes.

That looks like a system folder — you picked your home folder, Desktop, Downloads or another system folder. Cocoa works best with its own folder; choose Create a Notes Folder Instead, or Use It Anyway if you know why.

Reading the folder… / 1,200 files checked · 38 notes found for a long time — a large folder is being indexed. Stop cancels; you then read Indexing was cancelled. Choose a smaller folder, or rebuild the index from the Help menu.

Notes and files

A note I know exists does not appear in search. If it is archived, search leaves it out until you type is:archived; if it is in the Trash, it is under Recently Deleted. Otherwise run Help › Rebuild Index.

"…is not valid text." — the file is not UTF-8 text (a PDF or image renamed with a Markdown extension, say). Open it in Finder to see what it is.

"Could not coordinate access to …" — another program held the file locked, or a permission was refused. Wait a moment and open the note again; if it persists, check the file's permissions in Finder.

This note changed on disk — the orange bar above the page. Another app or another Mac changed the file while you had unsaved edits. Show Difference to compare, Use Theirs to take the disk's version, Keep Mine (Return) to keep yours. Nothing is lost either way; the other version is kept in Version History.

The wrong note opens from a link or There is no note called “…” — links match titles exactly. Fix the spelling inside the brackets, or click Create It to make that note.

A picture is gone. Pictures live in the folder's attachments folder next to the note; if you moved the note by hand in Finder, move the attachments folder too. Moving inside Cocoa moves both.

The editor

Clicking a line marks it instead of placing the cursor. You are holding a pen: the Highlighter button is lit. Click it, or press ⌃⌘H, to put the pen down.

I cannot change the font size. Size comes from heading levels (⌃⌘1 to ⌃⌘6, ⌃⌘0 for body). ⌘+ and ⌘- zoom the whole page.

Pressing Return in a table adds no row. Return moves to the cell below; the table's size comes from the picker when you insert it.

The outline is empty. It lists headings — No Headings — Headings appear here as you write them. Make a heading with ⌃⌘1.

Spelling cards keep appearing. Press Tab to accept a fix or keep typing to dismiss; turn them off under Settings › General › Check spelling while typing.

A pasted note shows odd symbols like <mark class="…">. Those are highlights written for a pen this folder does not have. Add a pen with that name in Settings › Pens or the folder's Highlighters, and they become highlights.

iCloud and sync

Downloading from iCloud stays on screen, then Still Waiting for iCloud. iCloud offloaded the note and has not delivered it. Check the Mac is online and signed in to iCloud (System Settings › Apple Account), then Try Again. Opening the notes folder in Finder and clicking the cloud icon beside the file also forces the download.

A Conflicts section appeared in the sidebar. iCloud made a conflict copy because the note was edited on two Macs at once. Right-click the row: Open the Original, compare, copy across what you need, then Move to Trash the copy.

Search finds different results on my two Macs. Each Mac has its own index; run Help › Rebuild Index on the one that is behind.

Study, Collections and Calendar

Nothing to Study / Nothing Collected Yet. Only named pens that collect or make cards fill these; the plain Highlight pen does not. Mark terms with a named pen (chapter 6).

Cocoa does not have permission to add events. Grant it in System Settings › Privacy & Security › Calendars, then click Add to Calendar again.

A date that is not a date appears in the Dates collection. Right-click it and choose Not a Date.

Capture and automation

No notes folder is open to capture into. Quick Capture, the share extension, the Services item or a Shortcut ran while Cocoa had no folder open. Open Cocoa, choose or create the folder, then capture again — the draft is kept in the capture panel.

Quick Capture does not appear when I press ⌥Space. Another app has that key, or the recorder was cleared. Set it again under Settings › General › Global shortcut.

Could not read Apple Notes. macOS refused the AppleScript access the importer needs. Allow Cocoa under System Settings › Privacy & Security › Automation, then import again.

Shortcuts and windows

A shortcut does nothing. Two commands may share it — Settings › Shortcuts reports 2 conflicting shortcuts. — or it belongs to macOS and is refused there in red. Rebind one of them.

The window is gone but the app is running. Click the book icon in the menu bar and choose Open Cocoa. If Run in the menu bar only is on, this is how the app works; turn it off in Settings › General to get a Dock icon back.

Notebook Not Found in a separate window — the note that window showed was deleted or the folder changed. Close the window.

Getting help with a formatting problem

Help › Copy Formatting Diagnostics copies a description of the open note's layout to the clipboard (the header reads Diagnostics copied). Paste it into a message when reporting a problem; it contains no note text.

Frequently asked questions

Where are my notes? In the folder you chose at setup — plain Markdown files, one per note, in folders that match your Library. File › Reveal in Finder (⌥⌘R) shows the open one.

Can I edit them in another app? Yes. Obsidian, iA Writer, a text editor — anything. Cocoa notices the change and reloads, or shows the orange bar if you were mid-edit.

Is there an iPhone or iPad app? No. With the folder in iCloud Drive, any Markdown app on the phone can open the files.

Does it need an account? No. Sync is iCloud Drive, which is Apple's; Cocoa has no server.

Why can't I pick a text color? Color would not survive in the file and would compete with the pens, which carry meaning. Use a pen.

How do I reopen this guide? Help › User Guide, the ? toolbar button, or ⌃⌘/. Skip the guide only closes it. The guided tour is separate: Help › Take the Tour (⌃⌥⌘/) runs it again in the main window.

What does Skip do to the tour? Nothing permanent. The tour closes and will not start by itself again; Help › Take the Tour replays it, and every chapter of this manual stays available.

How do I move my notes to another Mac? Put the folder in iCloud Drive (chapter 1), or copy the folder and open it there with I already have a Cocoa folder — open it….

What happens to backups if I forget the folder? They stay in this Mac's Application Support folder; Settings › Backups › Show in Finder finds them while the folder is open.

Summary

• Nearly every error appears under Could Not Open That Folder, with the system's reason under it.
• Help › Rebuild Index fixes search; it never changes notes.
• A lit Highlighter button means clicks mark instead of placing the cursor.
• iCloud problems are solved in System Settings and with Try Again; conflicts appear in the sidebar.

Common mistakes

• Reinstalling the app for a search problem — rebuild the index instead.
• Deleting a conflict copy before opening it — read it first.
• Looking for the guide in Settings — it is in the Help menu.

Best practices

• Keep the notes folder where you chose it; move it with Change Notes Folder…, not by dragging in Finder.
• Read the orange bar before clicking; both versions are kept, but choosing calmly is quicker.
• When something looks wrong on a page, Copy Formatting Diagnostics before changing anything.

Keyboard shortcuts used

Related features to learn next

• Chapter 13, Import, Export, Backups and Sync.
• Chapter 14, Settings and Customization.
• Chapter 1, Welcome and Setup — choosing where the notes live.