Troubleshooting

Running into an issue? This guide covers the most common problems reported by Pencil users along with step-by-step solutions. If your issue isn't listed here, reach out on the community Discord or open a support ticket.

Installation

Extension fails to install or activate

If the Pencil extension fails during installation or does not activate after installing, verify that you are logged into Claude Code and that the MCP (Model Context Protocol) server is reachable. A misconfigured or unreachable MCP endpoint is the most frequent root cause.

Missing Pencil icon in the IDE sidebar

If the Pencil icon does not appear after installation, create a new file with the .pen extension in your project, then close and reopen your IDE. The extension registers its icon when it detects a .pen file in the workspace.

Authentication

Activation email is delayed or missing

Activation emails can occasionally be delayed. Check your spam and promotions folders first. If the email has not arrived after 10 minutes, request a new one from the Pencil account page.

"Invite not found" error

This usually indicates a corrupt local cache. Uninstall the Pencil extension completely, restart your IDE, and reinstall from the marketplace. The fresh installation will pull a clean configuration.

Repeated login prompts

If you are asked to log in every time you open the IDE, your session token may not be persisting. Restart the IDE fully (not just reload the window) to force a fresh token write. On macOS, make sure the IDE has Keychain access.

Claude Code connection issues

If Pencil cannot connect to Claude Code, re-authenticate your Claude Code session from the terminal. Run the Claude Code login command, verify the token is valid, then restart the IDE so the extension picks up the refreshed credentials.

IDE-Specific Issues

Cursor: prompt editor not appearing

In Cursor, the Pencil prompt editor may not appear if your login session has expired. Open the Cursor command palette, sign out of Pencil, sign back in, and verify that the extension status shows "Connected".

VS Code: canvas does not load

The Pencil canvas in VS Code requires an open .pen file to initialise. Make sure you have a .pen file open in the active editor tab before launching the canvas panel.

Canvas & Selection

Selecting deeply nested elements

Use Cmd + Click (macOS) or Ctrl + Click (Windows/Linux) to pierce through wrapper elements and select the deepest child element directly.

Navigating to parent elements

Press Shift + Enter to move the selection up to the parent element of the currently selected node.

Component conversion not applying

If converting a selection to a component does not take effect, deselect all elements first, then reselect the target element and retry the conversion. The canvas occasionally caches stale selection state.

Import & Export

macOS file menu import not responding

On macOS the native file-menu import dialog can sometimes hang. As a workaround, drag and drop the file directly onto the Pencil canvas instead of using the menu.

Figma images not rendering after import

Bitmap images from Figma may lose their references during import. For best results, export assets from Figma as SVG before importing into Pencil. SVG assets retain full fidelity and are resolution-independent.

Export fails with "Process exited with code 1"

This error almost always means the Claude Code authentication token has expired or is invalid. Re-authenticate Claude Code from the terminal, then retry the export.

AI & MCP

Understanding local MCP execution

The MCP server runs locally on your machine. AI requests are processed through Claude Code but all file operations happen on your local filesystem. No project files are uploaded to external servers.

Folder access permissions

Pencil requires explicit permission to access project folders. If the AI cannot read or write files, check that you have granted folder access when prompted. You can reset permissions in the extension settings.

Known Limitations

Last updated: February 22, 2026