Debugging

Most styling bugs come down to one question: did Panda see your style? Start with panda debug to find out. Reach for logs, tracing, or a profile when the question is about speed.

See what Panda extracted

panda debug writes what Panda found in each file, the CSS it generated, and your resolved config.

pnpm panda debug
# Only scan some files
pnpm panda debug --include "src/components/**"

npx panda debug
# Only scan some files
npx panda debug --include "src/components/**"

yarn panda debug
# Only scan some files
yarn panda debug --include "src/components/**"

bun panda debug
# Only scan some files
bun panda debug --include "src/components/**"

It writes a debug folder inside your outdir:

• <file>.extract.json, one per source file: every css(), recipe, pattern, and JSX style Panda extracted, with its source position.
• styles.css: the CSS generated from the scanned files.
• config.json: your config after presets are merged. Check that it has the tokens and recipes you expect.
• system-info.json: your platform, Node version, config path, and how many files were scanned.

A file whose styles are missing usually shows up here first. If calls is empty, Panda didn't match your import or couldn't read the value:

{
  "calls": [
    {
      "category": "css",
      "name": "css",
      "alias": "css",
      "data": [
        {
          "kind": "value",
          "value": {
            "color": "gray.600",
            "p": "1.5",
            "_hover": { "color": "gray.900" }
          }
        }
      ],
      "span": { "start": 98, "end": 165 }
    }
  ],
  "jsx": [],
  "diagnostics": []
}

Useful flags:

• --include <glob> scans only the matching files. Repeat it for more globs.
• --onlyConfig writes just config.json and system-info.json.
• --dry prints everything to the terminal instead of writing files.
• --zip writes a single debug.zip, ready to attach to a bug report.

Read more log output

Add --log-level debug to any command to see where the time went:

panda cssgen --log-level debug

cssgen: parsed 2 files, wrote 21624 bytes to styled-system/styles.css, diagnostics: 0
cssgen: timings
config: 35ms
parse: 1ms
write: 1ms

The levels are silent, error, warn, info (the default), and debug.

Trace the compiler

--trace prints how long each step inside the Rust compiler took:

panda cssgen --trace

trace summary
total spans: 30
total span time: 6.32ms

span                                 count         total
--------------------------------------------------------
compile_config                           1        2.59ms
compile_css                              1      742.54us
load_tokens                              1      708.00us
stylesheet                               1      656.21us
file_parse                               2      274.63us
...

To see every step on a timeline, write a Chrome trace instead and open it in ui.perfetto.dev (opens in a new tab) or chrome://tracing:

panda cssgen --trace --trace-output chrome-json --trace-file trace.json

Tracing in Vite or PostCSS

Bundler plugins don't take CLI flags, so turn tracing on with environment variables:

PANDA_TRACE=trace PANDA_TRACE_OUTPUT=chrome-json PANDA_TRACE_FILE=trace.json vite build

• PANDA_TRACE sets what to record. trace records everything.
• PANDA_TRACE_OUTPUT is fmt (the default, a summary printed when the process exits) or chrome-json.
• PANDA_TRACE_FILE is where the Chrome trace is written. It defaults to .panda/trace.json.

Profile a slow build

--profile captures a full trace and a summary in one step. Use it when a build is slow and you want to share the result with us:

panda --profile

It writes two files:

• .panda/trace.json: the full timeline. Open it in ui.perfetto.dev (opens in a new tab) or chrome://tracing.
• .panda/timings.json: the total time per step, plus the slowest files.

--profile works with panda, panda cssgen, panda codegen, and panda debug.

Warnings and errors

Every warning and error Panda reports has a code. The Diagnostics reference explains each one and how to fix it. To use them in CI, add --format json or --format github, and --max-warnings <count> to fail the build when there are too many warnings.

FAQ

Why are my styles not applied?

Check that the @layer rules are set and that the CSS file is loaded. If you're not using PostCSS, make sure styled-system/styles.css is imported and that panda has run, or is running with --watch.

Why are one file's styles missing?

Run panda debug --include on that file and open its .extract.json:

• calls is empty. Panda didn't recognize the import. See the next question.
• The property is missing from value. Panda couldn't read the value at build time, for example a prop or state. See Dynamic styling.
• diagnostics isn't empty. The message explains what went wrong.

Do I need importMap for tsconfig path aliases?

Usually not. Panda reads the paths in your tsconfig.json, so an import like ~/styled-system/css works without extra config.

If you do set importMap, it replaces the default matching, so list every way you import the outdir:

export default defineConfig({
  // `~/styled-system/css` and `../styled-system/css`
  importMap: ['~/styled-system', 'styled-system']
})

Why is my IDE not showing styled-system imports?

Include the styled-system directory in your tsconfig.json so your editor picks up its types.

Why does the PostCSS plugin run so often?

Your bundler decides when to rerun PostCSS, and some rerun it more than needed. Panda caches its work and skips files that haven't changed, but if it still feels slow, run the CLI in watch mode next to your dev server instead:

{
  "scripts": {
    "dev": "concurrently \"next dev\" \"panda --watch\""
  }
}

If none of this helps, search the issues (opens in a new tab) or ask on Discord (opens in a new tab). When you open a new issue (opens in a new tab), attach the debug.zip from panda debug --zip.