Troubleshooting

Installation & Setup

A `.pen` file opens as text

Confirm the pen.dev extension is installed and enabled
Open the Command Palette and run pen.dev: Toggle Design Mode
Run pen.dev: New File to confirm the visual editor can create and open a document
Reload the IDE window if the pen.dev commands are missing

Don’t see the pen.dev icon

Confirm the extension is enabled
Look for pen.dev in the Activity Bar
Open the Command Palette and search for pen.dev
Reload the IDE window if the extension is enabled but its commands and icon are missing

The `pen` command is not found

Confirm Node.js is version 22 or later
Install the current package with npm install -g @pen.dev/cli
Confirm npm’s global binary directory is on PATH
Run pen version, not pen --version

See Installation for installation options.

Authentication & AI Providers

Check the spam or junk folder
Confirm the email address and use Resend code after the cooldown

An AI provider is not connected

Open Settings (⚙️) → Agents, choose the provider, and use one of the authentication methods shown for that provider.

If you selected Your Claude Code settings, run claude in a terminal and complete authentication.

See Authentication for account and provider setup.

Welcome File & Onboarding

Didn’t get the welcome file

Open the Command Palette and run pen.dev: Open Welcome File. You can also select Welcome from the pen.dev sidebar.

Add pen.dev to a project

Create a file such as design.pen in the project workspace
Open it in VS Code or Cursor

Canvas & Interface

Can’t navigate nested elements

Use keyboard shortcuts:

Cmd/Ctrl + Click: Deep select
Enter: Select children
Shift + Enter: Select parent

Or use the Layers panel:

Expand the hierarchy
Select an element from the list

Selection box colors

Light blue: Standard element
Magenta: Component origin
Purple: Component instance

Importing & Exporting

Images don’t paste from Figma

Images are not included when you copy and paste from Figma. For a full import with images, export a local .fig file from Figma and drag it onto the pen.dev canvas.

MCP & AI Integration

An external agent does not list pen.dev tools

The pen.dev MCP server runs locally.

Confirm the target pen.dev app is running and the intended document is open
Open Settings (⚙️) → MCP and confirm the integration is enabled for the external client
Restart or reconnect the external client after changing its MCP configuration

See AI Integration for setup details.

A tool is present but a call fails

Ask the connected agent to run read_skill() and inspect the document with get_app_state() before retrying the failed call.

Advanced users can call these tools directly from pen interactive.

pen.dev changed an MCP configuration file

Enabling an integration in Settings (⚙️) → MCP adds or updates the pencil entry in that client’s MCP configuration. Disable the integration to remove the entry.

Saving & Version Control

Desktop changes are visible but the original file has not changed

For an existing .pen file, the pen.dev desktop app writes a separate recovery backup in the background. The original file changes only after File → Save or Cmd/Ctrl + S succeeds.

Documents created from the desktop dashboard are saved automatically.

pen.dev reopened a file with “Recovered changes”

pen.dev found a newer recovery backup after an unexpected stop. Review the restored document, then save it to write those changes to the original .pen file.

The recovery backup is not version history and does not replace Git.

Platform-Specific

Windows desktop app

The pen.dev desktop app is available for Windows. See Installation for the current download.

Linux desktop app

The pen.dev desktop app is available for Linux. See Installation for the available packages.

CLI Issues

Authentication required

Run pen login or set PEN_CLI_KEY. Agent, export, and interactive commands require CLI authentication.

A command fails

Run pen --help or pen interactive --help from the installed CLI
Check the process exit status before using an output file
In the interactive shell, call save() before exit() to write changes

See the pen.dev CLI reference for current commands and options.

Getting More Help

Review the relevant documentation

Report a reproducible problem

Include:

Operating system and version
pen.dev app and exact version
IDE and extension version, when applicable
CLI command with secrets removed, when applicable
Selected AI provider and authentication method, without credentials
Exact error message
Steps to reproduce
A minimal non-sensitive .pen file, screenshot, or log excerpt when useful

Never include passwords, session tokens, API keys, verification codes, or private design content in a public report.

Prevention Tips

Keep pen.dev and the IDE extension up to date
Keep the selected AI provider authenticated when using AI features
Keep .pen files in the project workspace when using the IDE extension
Save existing files with Cmd/Ctrl + S
Use Git commits for version history
Do not edit .pen files manually