Skip to content
Documentation
Troubleshooting
Valdr Packs

Valdr Packs

Common issues when importing, validating, and using Valdr Packs.

I imported a pack but the agents do not appear

Symptom: You imported a pack through Settings > Valdr Packs, but the expected agents do not appear in the UI.

Likely cause: The import was not committed, the preflight step reported blocking issues, or you are looking at a different Valdr data directory than the one you imported into.

Fix:

  1. Re-open Settings > Valdr Packs and run the import again
  2. Review the preflight summary carefully before committing
  3. Check System Monitoring and confirm the current PM DB Path belongs to the Valdr instance you intended to update

I unpacked a pack archive to disk but nothing changed

Symptom: You extracted a .valdr-pack.tar.gz archive into a repo or local folder and expected Valdr’s agent list to update automatically.

Likely cause: Extracting the archive only gives you the pack files. It does not apply those agents, prompts, and capabilities to the running Valdr database.

Fix: Use Settings > Valdr Packs > Import Pack to import the archive into Valdr. Unpacked directories are useful for inspection, version control, and valdr validate-pack, but import is what applies the pack to the app.

Pack import shows conflicts

Symptom: Importing a pack shows a conflict preview with existing agents, prompts, or capabilities.

Likely cause: You already have records with the same keys from an earlier import or a different pack.

Fix: Review the preflight result before committing:

  • Add means the item is new
  • Overwrite means the existing item will be replaced
  • Skip means the incoming item will not be applied

If you want to preserve the current version, do not commit the import. If the new pack is the source of truth, commit it and let Valdr update the matching records.

Pack validation fails

Symptom: valdr validate-pack <pack-dir> reports errors.

Likely cause: The pack structure or metadata does not match the supported format.

Fix: Re-run validation on the unpacked pack directory and fix the reported errors. Common causes include:

  • Missing pack.yaml
  • Unsupported or missing schemaVersion
  • Malformed .agent.yaml files
  • Agents referencing prompts or capabilities that are not included in the pack

See Valdr Packs > Authoring workflow for the supported structure.

Pack imports, but an agent is missing prompt or capability content

Symptom: The agent record exists after import, but launches behave as though prompt or capability content is missing.

Likely cause: The archive did not include every dependency the agent needs, or the import preflight warnings were ignored.

Fix:

  1. Run valdr validate-pack <pack-dir> on the unpacked source
  2. Fix the reported dependency or structure issues
  3. Re-export the pack
  4. Import the new archive again and review preflight warnings before commit

Downloaded pack tarball is empty or corrupted

Symptom: tar -xzf valdr-pack-*.tar.gz fails or extracts an empty result.

Likely cause: The download was incomplete or the archive is damaged.

Fix:

# Inspect the archive before extracting
tar -tzf valdr-pack-*.tar.gz | head

If that fails, download the archive again from projectviking-ai/valdr-packs releases.

Pack references providers I do not have configured

Symptom: A pack import succeeds, but launching its agents fails because the expected provider or preset setup is missing.

Likely cause: The pack assumes providers or presets you have not configured on this machine.

Fix:

  • Open Settings > Providers and register the missing provider
  • Open Settings > Agent Presets and create or import a preset that matches the agent workflow you want to run
  • See Provider Configuration for provider setup details

Related

Sessions & Worktrees