# 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](/valdr/docs/ui/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](/valdr/docs/valdr-packs/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:**

```bash
# 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](https://github.com/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](/valdr/docs/valdr-provider-packs/overview/) for provider setup details

## Related

- [Valdr Packs overview](/valdr/docs/valdr-packs/)
- [Pack authoring workflow](/valdr/docs/valdr-packs/workflow/)
- [projectviking-ai/valdr-packs releases](https://github.com/projectviking-ai/valdr-packs/releases)