> ## Documentation Index
> Fetch the complete documentation index at: https://filepacks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common filepacks problems, what they mean, and how to recover quickly.

Use this page when a command exits unexpectedly or an artifact does not behave the way you expect.

## Pack problems

### `Input path does not exist`

Cause: `filepacks pack` was given a directory path that does not exist.

Fix:

```bash theme={null}
ls ./your-input-directory
npx filepacks pack ./your-input-directory --output ./artifact.fpk
```

### `Input path is not a directory`

Cause: `pack` only accepts a directory as input.

Fix: pass a directory, not a single file.

### `Output path must end with .fpk`

Cause: `pack --output` was given a path without the required `.fpk` extension.

Fix:

```bash theme={null}
npx filepacks pack ./your-input-directory --output ./artifact.fpk
```

### `Unsupported file type at:`

Cause: the input contains a non-regular file such as a symlink, device, socket, or pipe.

Fix: package only regular files.

The current implementation rejects non-regular file inputs.

## Inspect and verify problems

### `Artifact path must end with .fpk`

Cause: `inspect`, `verify`, or `compare` was given a path without the `.fpk` extension.

Fix: pass a real artifact path ending in `.fpk`.

### `Artifact path does not exist`

Cause: the artifact path passed to `inspect`, `verify`, or `compare` does not exist.

Fix:

```bash theme={null}
ls ./artifact.fpk
npx filepacks inspect ./artifact.fpk
```

### `Artifact manifest.json must be the first archive entry`

Cause: the archive does not follow the public `.fpk` format.

Fix: recreate the artifact with `filepacks pack`.

### `Unsupported archive entry type: directory`

Cause: the archive contains a non-file tar entry.

Fix: use a valid `.fpk` artifact. The public format allows only file entries.

### `Invalid manifest.json:`

Cause: the manifest is malformed, unsupported, or violates the public format rules.

Examples include:

* invalid JSON
* unsupported `format_version`
* duplicate file paths
* invalid payload digest
* typed artifact fields such as `schema_version` or `artifact_type`

Fix: recreate the artifact with the current public CLI or core package.

### `verify` reports `ok=false`

Cause: payload files no longer match the manifest.

Mismatch codes may include:

* `missing_payload_file`
* `unexpected_payload_file`
* `size_mismatch`
* `hash_mismatch`
* `digest_mismatch`
* `manifest_invalid`
* `archive_malformed`

Fix: inspect the artifact source, then recreate the `.fpk` file from a trusted directory.

## Compare problems

### `compare` exits `20`

Cause: the baseline and candidate differ structurally.

This is expected when any file was added, removed, or changed.

Use the printed `added_file=...`, `removed_file=...`, and `changed_file=...` lines to see what changed.

### `compare` exits `1`

Cause: the command could not run correctly. Common reasons are:

* one of the paths does not exist
* one of the paths does not end in `.fpk`
* one of the artifacts is malformed

Fix: verify that both paths are valid artifacts first:

```bash theme={null}
npx filepacks verify ./baseline.fpk
npx filepacks verify ./candidate.fpk
```

## A good recovery order

When you are unsure what failed:

1. Confirm the path exists.
2. Run `inspect` for a quick summary.
3. Run `verify` to confirm integrity.
4. Only then run `compare`.