CLI & Config

Diagnostics Reference

What Panda's warnings and errors mean, how to control them, and how to fix each one.

When Panda finds a problem in your config or source files, it reports a diagnostic instead of stopping:

warning unknown_condition src/App.tsx:4:9 unknown condition `_hovr`, did you mean `_hover`?

Each line gives you a severity, a code, a location, and a message. Look up the code below to see what caused it and how to fix it.

Severity

error fails the build. No CSS is emitted for the broken part.
warning means the build continued, but some CSS may be missing or different from what you expect.
info is a heads-up. Nothing is wrong yet.

A config file that can't load at all (syntax error, missing preset) also stops the build. The CLI reports it as an error diagnostic like the others.

Controlling diagnostics

In the CLI

Fail CI on any warning:

panda --max-warnings 0

Warnings never change the exit code on their own. --max-warnings <n> fails the run when there are more than n.

Other useful flags:

--format github prints annotations that show up inline on GitHub pull requests.
--json prints a diagnostics array you can process in scripts.
--log-level error hides warnings and info. It only changes what's printed, not the exit code.

In your config

The validation option controls the config checks (the config_* codes):

panda.config.ts

export default defineConfig({
  validation: 'error' // 'none' | 'warn' (default) | 'error'
})

'warn' reports them as warnings.
'error' turns them into build failures.
'none' skips them.

It doesn't affect extraction, staticCss, or design system codes. You can't silence individual codes.

In bundler plugins

PostCSS: errors fail the build, warnings go to result.warn(), info isn't printed.
Vite: everything is reported as a warning and the build never fails. Run panda --max-warnings 0 in CI if you need a gate.

Codes

The code is stable. Messages may be reworded between releases, so match on the code in any tooling you build.

Your source files

unknown_condition (warning): a condition like _hovr doesn't exist. The message suggests the closest match.
panda_call_unextractable (warning): a style call got a value Panda can't read at build time, like css(props.styles) or css({ [key]: 'red' }). Pass a literal object instead, or generate the CSS with staticCss. Turned off when jsxFramework is set, since components often pass styles through props.
imported_recipe_raw_dynamic (warning): button.raw({ size }) with a dynamic size, where button is a cva from another file. Pass literal variant values, or call .raw() in the file that defines the recipe.
invalid_color_opacity_modifier (warning): bg: 'red/abc'. Use a number (red/40) or an opacity token (red/half).
deprecated_utility_used (warning): you used a utility marked deprecated in the config.
deprecated_token_used (warning): token('…') refers to a token marked deprecated.
js_parse_error (warning): the file has a syntax error. Panda extracted what it could, so some styles may be missing.
transform_callback_failed (warning): a utility or pattern transform, or a parser:before hook, threw or returned something that isn't a style object. The message names the utility and value.
source_not_found, source_read_failed (warning): an included file was deleted or couldn't be read. Panda keeps its last CSS for that file.

`firstThatWorks`

These cover firstThatWorks fallbacks. No CSS is emitted for an error.

first_that_works_arity_invalid (error): fewer than 2 values. One value has nothing to fall back to.
first_that_works_member_invalid (error): a value is an object, array, boolean, or null. Each must be a single CSS value.
first_that_works_unbalanced (error): a string like 'firstThatWorks(red, blue' is missing a parenthesis.
first_that_works_nested (error): firstThatWorks inside firstThatWorks.
first_that_works_importance_mixed (error): only some values are !important. Mark all or none.
first_that_works_custom_property (warning): used on a --custom-property. Write the fallback as var(--x, fallback) instead.
first_that_works_transform_unsupported (warning): the values expand to different CSS properties through a utility, so they can't fall back to each other.

Tokens

config_token_missing_value (warning): a token has no value. Write red: { value: '#f00' }, not red: '#f00'.
config_token_nested_value (warning): a semantic token has value: { value: … }.
config_token_key_contains_space (warning): a token name contains a space.
config_token_missing_reference (warning): {colors.brand} points to a token that doesn't exist.
config_token_unknown_reference (warning): a reference can't be resolved.
config_token_self_reference (warning): a token refers to itself.
config_token_circular_reference (warning): tokens refer to each other in a loop. The message shows the chain.

Config

config_hooks_removed (error): root hooks was removed in v2. Move them to plugins: [{ name: 'local', hooks: { … } }].
config_artifact_name_conflict (warning): a recipe, slot recipe, and pattern share a name. Rename one.
config_breakpoint_units_mixed (warning): breakpoints mix units, like px and rem. Use one.
config_condition_selector_invalid (warning): a condition selector is missing &, or a block condition doesn't end in '@slot'.
config_condition_array_unsupported (warning): array conditions were removed in v2. Use the block form ending in '@slot'.
config_utility_values_invalid (warning): a utility's values object contains style objects. Values must be strings, numbers, or booleans. Return styles from transform.
config_theme_name_invalid (warning): a themes key uses characters other than letters, digits, -, and _.
config_container_invalid (warning): containerNames isn't an array, or containers isn't an object of string sizes.
config_container_name_invalid (warning): a container name or size contains a space, /, or @.
config_container_units_mixed (warning): container sizes mix units.
config_container_condition_conflict (warning): two container definitions produce the same condition with different queries.
preset_resolution_failed (error): a preset couldn't be imported. Check that it's installed.
include_package_resolution_failed (error): a package in include couldn't be resolved.
config_load_error (error, CLI): the config file failed to load. The message has the underlying error.

Stylesheet output

layer_name_collision (warning): two layers entries use the same name, so the cascade order is ambiguous.
global_var_utility_conflict (warning): a plain globalVars value overrides a utility's @property registration. Pass an @property object instead.

`staticCss`

See Static CSS Generation.

static_css_property_unknown (warning): staticCss.css names a property with no utility.
static_css_token_reference_unknown (warning): a custom property refers to a token that doesn't exist.
static_css_recipe_unknown (warning): staticCss.recipes names a recipe that doesn't exist.
static_css_recipe_variant_unknown, static_css_recipe_variant_value_unknown (warning): the recipe exists but the variant or value doesn't.
static_css_pattern_unknown (warning): staticCss.patterns names a pattern that doesn't exist.
static_css_wildcard_empty (warning): a '*' wildcard matched no values, so nothing was generated.
static_css_wildcard_large (info): a wildcard expands to more than 250 values. Consider listing the ones you use.

Design systems

See Consume with Panda.

Setup (all errors):

design_system_in_include: a design system is listed in include. Move it to designSystem.
design_system_manifest_not_found: the package isn't installed, or wasn't built with panda lib.
design_system_manifest_not_exported: the package doesn't export ./panda/*.
design_system_manifest_invalid: the package's panda/lib.json is malformed. Rebuild it with panda lib.
design_system_resolve_failed, design_system_preset_load_failed: the package or its preset couldn't be loaded.
design_system_parent_not_found: the design system extends another that isn't installed.
design_system_cycle: two design systems extend each other.
design_system_duplicate_name, design_system_name_collision: two design systems have the same name.
design_system_unsupported_specifier: a specifier like workspace: isn't supported.
design_system_export_missing: the package is missing one of its generated styled-system exports. Rebuild it with panda lib.
design_system_version_mismatch: the package was built with an incompatible version of panda lib. Upgrade or rebuild it.
design_system_peer_range_unsatisfied: the package requires a Panda version you don't have installed.

Build compatibility:

design_system_buildinfo_stale (warning or error): the design system's build is out of date. Run panda lib in its package. It's a warning when Panda could fall back to the source files.
design_system_option_mismatch (warning or error): the design system was built with different options than your project.
design_system_utility_unregistered (warning): the design system uses a utility your config doesn't define. Add its preset.
design_system_artifact_conflict (warning): your config and the design system define a recipe or pattern with the same name. Yours is merged over theirs.
design_system_token_conflict (info): your config and the design system define the same tokens. Yours win.

When running panda lib (all warnings):

design_system_spec_not_publishable, design_system_files_not_publishable, design_system_export_overwritten: the package output won't publish correctly. The message says what to change.