Vellum
Docs
Docs / Help / Common Issues

Common Issues

Things that go wrong and how to fix them. If your issue isn't here, check Getting Help for where to ask.

Installation

“Vellum can't be opened because it is from an unidentified developer”

This is a standard macOS Gatekeeper warning for apps not distributed through the App Store.

Fix: Right-click (or Control-click) the app in Finder → select “Open” → click “Open” in the dialog. This only happens once.

The app won't launch / crashes on startup

Try:

  1. Make sure you're on macOS 14 (Sonoma) or later.
  2. Check that the assistant daemon is running. You can verify in the menu bar — the Vellum icon should be visible. If it's not, try relaunching the app.
  3. Try deleting and re-downloading the app.
  4. Check Console.app for crash logs (filter by com.vellum.vellum-assistant) if the issue persists.

My API key isn't working

Check:

  1. Make sure you're using an Anthropic API key (starts with sk-ant-). Keys from other providers won't work.
  2. Verify the key is active in your Anthropic Console.
  3. Check that you have available credits or an active billing plan.
  4. If you're using managed mode (Vellum account sign-in), you don't need a separate API key.

Permissions

“Operation not permitted” error

A macOS system permission is missing. Your assistant needs the relevant permission granted through System Settings.

Fix: Go to System Settings → Privacy & Security and find the relevant permission category:

  • Accessibility — required for mouse/keyboard control (computer use)
  • Screen Recording — required for seeing screen content
  • Microphone — required for voice input

Toggle Vellum on for the relevant permission and try again.

I clicked “Don't Allow” by accident

No problem. Your assistant won't retry automatically. Just tell it: “Try that again” or “Go ahead and access that file.” It'll send a new permission prompt.

My assistant keeps asking for the same permission

Each individual action gets its own prompt by default. If your assistant needs to read three different files, that's three separate prompts.

Fix: Use broader approval scopes to reduce prompts:

  • Allow for 10 minutes — auto-approves similar actions for 10 minutes
  • Allow for this conversation — auto-approves until the conversation ends
  • Always Allow — creates a persistent rule for this pattern (you can scope it to a specific file, directory, or everywhere)

Your trust rules accumulate over time in ~/.vellum/protected/trust.json. The more you use your assistant, the fewer prompts you'll see. See The Permissions Model for details.

Skills & services

A skill won't load

Try:

  1. Ask your assistant: “Why isn't the [skill name] skill working?”
  2. Check if the skill requires setup (OAuth connection, API key, etc.)
  3. Some skills are gated behind feature flags. If a skill doesn't appear in the catalog, it may not be enabled for your setup yet.

OAuth connection failed (Gmail, Google Calendar, Slack)

Try:

  1. Make sure you have an active internet connection.
  2. Try the connection again: “Reconnect my Gmail”
  3. Check that you're logging into the correct account.
  4. If using a corporate Google or Slack account, your organization may block third-party OAuth apps. Check with your IT department.

Gmail isn't working

Check:

  1. Has Gmail been connected? Ask: “Is Gmail set up?”
  2. If not, run setup: “Connect my Gmail”
  3. If it was working before, your OAuth token may have expired. Try: “Reconnect my Gmail”
  4. Make sure you granted the correct scopes during OAuth (Gmail read/write access).

My custom skill isn't working

Check:

  1. Is the skill in ~/.vellum/workspace/skills/? Check that it has a valid SKILL.md and TOOLS.json.
  2. Ask your assistant to load it explicitly: “Load the [skill name] skill”
  3. Check for errors in the tool executors. Ask: “Show me the [skill name] skill code”
  4. Third-party skill tools are always prompted for approval. Make sure you're approving the tool executions.

Channels & connections

Telegram bot isn't responding

Check:

  1. Is your Mac running? The assistant daemon needs to be active for Telegram messages to be processed (unless you're using managed mode).
  2. Is the gateway reachable? Telegram webhooks need a public URL. Ask: “Check my Telegram connection”
  3. Try re-registering the webhook: “Reconnect Telegram”
  4. Verify your bot token is still valid with BotFather.

iOS pairing isn't working

Try:

  1. Make sure both devices are on the same network (or that your Mac's gateway is reachable from your phone).
  2. QR codes expire after 5 minutes. Generate a new one from Settings → Connect.
  3. After scanning the QR code, you need to approve the device on your Mac.
  4. If pairing worked before but stopped, your credentials may have expired. Re-pair with a new QR code.

Slack connection drops or isn't working

Check:

  1. Slack uses Socket Mode, which requires both a Bot Token and an App Token. Make sure both are configured.
  2. If the connection drops, it usually reconnects automatically. Try: “Reconnect Slack”
  3. Make sure the Slack app has the right scopes (channels:history, chat:write, app_mentions:read at minimum).

Computer use

Computer use isn't working

Check:

  1. Accessibility permission must be granted in System Settings → Privacy & Security → Accessibility.
  2. Screen Recording permission must be granted in System Settings → Privacy & Security → Screen Recording.
  3. Both permissions may require restarting the app after granting them.

Computer use session is stuck or looping

The assistant has built-in loop detection — if it detects the screen isn't changing after repeated actions, it will pause and ask for guidance. Sessions are also capped at 50 steps.

If it's stuck: Cancel the session and describe what you're trying to accomplish differently. Sometimes the assistant needs a more specific instruction about which element to click or what app to use.

Computer use clicked the wrong thing

Cancel the session immediately. The assistant reads the accessibility tree to identify elements by name, but complex UIs can sometimes cause misidentification. Undo the action manually (Cmd+Z if applicable), then retry with more specific instructions like “click the blue Submit button in the bottom right.”

Voice

Voice input isn't picking up my speech

Check:

  1. Microphone permission must be granted in System Settings → Privacy & Security → Microphone.
  2. Make sure you're holding the activation key (default: Fn) long enough. There's a 300ms hold period before recording starts to filter out accidental presses.
  3. If you pressed another key during the hold period, recording won't start. Release and try again with just the activation key.
  4. Check your activation key setting — say “Set up voice” to reconfigure.

Voice transcription is inaccurate

Voice input uses Apple's built-in speech recognition. Accuracy depends on microphone quality, background noise, and accent. Try speaking more slowly and clearly, or use an external microphone. For critical instructions, consider typing instead.

Performance

My assistant is slow to respond

Response time depends on:

  1. The AI model provider — Cloud API latency varies. Complex requests take longer.
  2. Tool execution — Actions like web browsing or API calls add time.
  3. Context size — Very long conversations with lots of loaded skills can slow things down. The assistant compacts old messages automatically, but this takes a turn to process.

Try:

  • Start a new conversation (resets context length)
  • Check your internet connection
  • Try a simpler request to see if the issue is task-specific

My assistant forgot something I told it

Possible reasons:

  1. It wasn't extracted. The memory system extracts facts automatically, but low-value messages (“ok,” “thanks”) are filtered out. For important info, be explicit: “Remember this: [fact].”
  2. It's in a different conversation. Memories carry across conversations, but conversation history doesn't. Important context should be saved to memory or workspace files.
  3. It was saved but not recalled. Memory search uses hybrid retrieval (semantic + keyword). Try asking more specifically: “What do you remember about Project Moonshot?” You can also use the memory tool directly: “Search your memory for [topic].”
  4. It went stale. Memories have lifetimes based on their type — events last about 3 days, projects about 2 weeks, preferences about 3 months. Memories mentioned across multiple conversations age more slowly. If something important expired, tell your assistant again and it will re-save it.

Workspace

My workspace files look wrong or corrupted

Your workspace is plain text files. If something looks off:

  1. Open the file in a text editor and check for formatting issues.
  2. If a file is genuinely corrupted, delete it. Your assistant will recreate default versions of SOUL.md, IDENTITY.md, and USER.md on next launch.
  3. If you're using version control (git), you can revert to a previous state.

I accidentally deleted a workspace file

  • IDENTITY.md, SOUL.md, USER.md — Your assistant recreates these with defaults on next launch. You'll lose your customizations but not your assistant.
  • Memories — Stored in a SQLite database and vector store in ~/.vellum/workspace/data/. If deleted, saved memories are gone. There's no automatic backup.
  • Custom skills — If you delete a skill folder from ~/.vellum/workspace/skills/, that skill is gone. Rebuild it or reinstall from the community registry.
  • Credentials — Stored separately in ~/.vellum/protected/. Deleting workspace files won't affect your credentials.
Pro tip: Consider putting your workspace under version control with git. It's a folder of text files, perfect for git. You can also use vellum retire from the CLI to archive your entire workspace as a tarball before making major changes.