Skip to main content

Troubleshooting

Solutions for common issues you may encounter when using Pitch Smith. Each entry follows a consistent problem -- cause -- solution format so you can quickly find and fix your issue.

How to use this guide

Scan the headings below to find the symptom that matches what you are experiencing. Each section describes the likely cause and provides step-by-step instructions to resolve the problem.

Plugin Not Loading / Commands Not Found​

Symptom​

You type a Pitch Smith command (for example, /pitchsmith:build-one) in Claude Code and receive an error like "command not found" or "unknown command", or the plugin does not appear to be registered at all.

Cause​

The Pitch Smith plugin may not be installed, may not be registered with Claude Code, or Claude Code may need to be restarted to pick up the plugin.

Solution​

  1. Verify the plugin is installed. Check that the pitchsmith-plugin/ directory exists in your Claude Code plugins location:

    ls ~/.claude/plugins/pitchsmith-plugin/

    If the directory does not exist, install the plugin by following the Install Guide.

  2. Check your Node.js version. Pitch Smith requires Node.js 18 or later:

    node --version

    If your version is below 18, update Node.js before proceeding.

  3. Restart Claude Code. After installing or updating the plugin, restart your Claude Code session so it re-scans available plugins:

    claude

  4. Verify plugin registration. After restarting, confirm that Pitch Smith commands are available:

    /pitchsmith

    You should see the Pitch Smith skill router respond with a welcome message or status summary.

Plugin location may vary

If you installed the Pitch Smith VS Code extension instead of the standalone CLI plugin, the plugin files are managed by the extension. In that case, ensure the extension is enabled in VS Code and that Claude Code is running within a VS Code integrated terminal.

Slides Not Rendering Correctly​

Symptom​

A built slide appears broken in the Slide Viewer or browser -- elements are misaligned, text overflows, the background is missing, or the slide looks unstyled.

Cause​

This usually happens when the theme CSS is not applied correctly, the template HTML contains errors, assets are missing, or the Slide Viewer cache is stale.

Solution​

  1. Check the theme file. Verify that .slide-builder/theme.json exists and contains valid JSON:

    cat .slide-builder/theme.json | head -5

    If the file is missing or corrupt, re-run /pitchsmith:setup to regenerate it.

  2. Inspect the slide HTML. Open the slide file directly in a browser to see if the issue is in the HTML or in the viewer:

    open output/<your-deck-slug>/slides/slide-1.html

    If the slide looks correct in a standalone browser but not in the viewer, the viewer may need a refresh.

  3. Refresh the viewer manifest. Regenerate the slide manifest so the viewer picks up the latest content:

    /pitchsmith:refresh

  4. Rebuild the slide. If the HTML itself is malformed, set the slide status back to "pending" in plan.yaml and rebuild:

    /pitchsmith:build-one
Check for missing assets

If a slide references images or brand assets that do not exist on disk, those elements will appear as broken placeholders. Verify that all referenced files in output/<deck-slug>/slides/ and .slide-builder/brand-assets/ are present.

Brand Extraction Failing​

Symptom​

Running /pitchsmith:setup to extract brand assets fails, produces incomplete results, or errors out during the extraction process.

Cause​

Brand extraction can fail when the source material is in an unsupported format, the source URL is unreachable, or there are not enough brand signals in the provided assets.

Solution​

  1. Check source format. Brand extraction works best with:

    • Company website URLs (for example, https://yourcompany.com)
    • PDF brand guidelines
    • Image files containing logos, color palettes, or typography samples

    If you provided an unsupported file type, try a different source format.

  2. Verify network access. If extracting from a URL, confirm that the URL is reachable:

    curl -I https://yourcompany.com

    If the site requires authentication or blocks automated access, download the relevant pages as PDFs and use those instead.

  3. Provide more source material. If extraction produces sparse or inaccurate results, add more brand assets:

    • Upload additional PDF files with brand guidelines
    • Provide logo files in SVG or PNG format
    • Include screenshots of existing presentations or marketing materials

  4. Use manual brand setup as fallback. If automated extraction is not working, you can set up your brand manually by editing theme.json directly. See Customize Theme for guidance on manual theme editing.

Brand extraction tips

For the best results, provide a brand guidelines PDF alongside your website URL. Brand guidelines typically contain explicit color codes, font names, and usage rules that make extraction much more accurate.

Export Errors​

Symptom​

Exporting slides to PNG, PDF, or PPTX fails, produces blank output, or hangs indefinitely.

Cause​

Export operations depend on external tools (Puppeteer for PNG/PDF, Node.js libraries for PPTX). Failures typically stem from missing dependencies, insufficient system resources, or incompatible slide content.

Solution​

PNG and PDF Export​

  1. Verify Puppeteer is available. PNG and PDF exports use Puppeteer to render slides in a headless browser:

    node -e "require('puppeteer')" 2>&1

    If this command errors, Puppeteer may not be installed. It is typically bundled with the plugin, but you can install it manually:

    npm install puppeteer

  2. Check Node.js version. Puppeteer requires Node.js 18 or later:

    node --version

  3. Try exporting a single slide first. If batch export is failing, test with a single slide to isolate whether the issue is specific to one slide or systemic.

PPTX Export​

  1. Check for complex HTML. PPTX export converts slide HTML to PowerPoint format. Slides with extremely complex layouts (deeply nested elements, custom SVG graphics) may not convert perfectly. Simplify the slide layout if possible.

  2. Verify disk space. PPTX generation creates temporary files. Ensure you have sufficient disk space in your working directory.

Export limitations

Not all visual elements translate perfectly to every export format. PNG and PDF exports are high-fidelity (they render the exact HTML). PPTX export approximates the layout with editable text boxes and positioned images -- some visual flourishes may be simplified.

Viewer Not Opening​

Symptom​

After building slides, the Slide Viewer does not open automatically, or attempting to open it manually fails.

Cause​

The Slide Viewer may not open if the VS Code extension is not installed, if there is a port conflict, or if the viewer panel failed to initialize.

Solution​

  1. Check the VS Code extension. The Slide Viewer is part of the Pitch Smith VS Code extension. Verify it is installed:

    • Open VS Code
    • Go to Extensions (Cmd+Shift+X on macOS, Ctrl+Shift+X on Windows/Linux)
    • Search for "Pitch Smith"
    • Confirm the extension is installed and enabled

  2. Open the viewer manually. Use the Command Palette:

    • Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
    • Type "Pitch Smith: Open Slide Viewer"
    • Select the command

  3. Check for port conflicts. If the viewer serves content via a local HTTP server, another application may be using the same port. Check the VS Code output panel for error messages about port conflicts.

  4. Restart VS Code. If the viewer panel is in a broken state, close and reopen VS Code to reinitialize the extension.

Presenter mode alternative

If the in-editor viewer is not working, you can present slides in your browser using the present command:

/pitchsmith:present

This starts a local HTTP server and opens your deck in a full browser window.

Search Not Working in Dev Mode​

Symptom​

When running the Docusaurus dev server (npm start), the search bar displays the message "Search index only available when you run docusaurus build" and no search results appear.

Cause​

The search plugin (@easyops-cn/docusaurus-search-local) generates its search index during docusaurus build via a postBuild hook. The dev server (docusaurus start) uses webpack-dev-server with hot module replacement and does not trigger this hook, so no search index is available. This is expected behavior, not a bug.

Solution​

Use the preview script to build and serve the site locally with a working search index:

cd pitchsmith-website
npm run preview

This runs docusaurus build followed by docusaurus serve, giving you a local preview of the production site with fully functional search.

When to use each command
  • npm start -- Fast development with hot reload, but search is unavailable.
  • npm run preview -- Full production build served locally, with working search. Use this when you need to test or verify search behavior.
  • npm run build -- Production build only (output in build/). Use this for deployment.

Common Error Messages​

"No theme found" or "Theme file not found"​

Cause: Pitch Smith commands that require a theme (build, edit, theme-edit) cannot find .slide-builder/theme.json.

Solution: Run brand setup to create your theme:

/pitchsmith:setup

"Workflow not found in plugin or user overrides"​

Cause: A command's workflow file could not be located in either the plugin directory or your local overrides.

Solution:

  1. Verify the plugin is properly installed (see Plugin Not Loading above).
  2. If you have ejected and modified workflows, verify the expected file exists in .slide-builder/workflows/.

"Plan file not found" or "No deck plan exists"​

Cause: Build commands require a deck plan (plan.yaml) to know which slides to generate.

Solution: Create a deck plan first:

/pitchsmith:plan-deck

"Cannot read catalog" or "Catalog not found"​

Cause: Template-related commands cannot find the template catalog at .slide-builder/catalog/.

Solution:

  1. Verify your workspace is scaffolded (/pitchsmith initializes the workspace if needed).
  2. Check that .slide-builder/catalog/catalog.json exists and contains valid JSON.

"Puppeteer launch failed" or "Browser not found"​

Cause: Export commands that use Puppeteer (PNG, PDF) cannot launch the headless browser.

Solution:

  1. Ensure Puppeteer is installed (see Export Errors above).

  2. On Linux systems, you may need additional system libraries. Run:

    npx puppeteer browsers install chrome

  3. If running in a restricted environment (Docker, CI), ensure the environment allows headless browser execution.

Environment-specific issues

If you are running Pitch Smith in a Docker container, CI pipeline, or remote development environment, headless browser features (export, sample generation) may require additional configuration. Ensure the environment has the necessary system libraries for Chromium.

See Also​

Related documentation

The following pages provide deeper context that may help resolve issues:

  • Install Guide -- Full installation instructions and system requirements
  • Quickstart -- Verify your setup is working with a quick end-to-end test
  • Commands Reference -- Complete command reference with expected behavior for each command
  • Directory Structure -- Where Pitch Smith files are stored and what each directory contains
  • Customize Theme -- Manual theme editing as a fallback when automated tools encounter issues
  • Build Slides -- Slide building workflow, including handling build failures