provider directory failed to load: causes and recovery

provider directory failed to load sounds like an internal error; it is usually a path, permission, or format problem. Reinstalling does not help, because the provider directory lives in the data directory.

Three checks

Check in this order; most cases end in the first two.

Path problems are most common. The provider directory is under the data directory; a changed data directory, migration, or permission change makes it unavailable.

Permissions are next. The service user and terminal user may differ; a directory readable by one may not be readable by the service.

Format problems follow. Hand-edited configuration with missing fields or wrong types fails parsing.

Path and data directory

Confirm which directory the service actually reads.

1. Confirm the data directory with dsh --dump-config or configuration.
2. Confirm the provider directory's location and existence.
3. Check whether the service runs under a different data directory.
4. Compare with the documentation for the expected structure.
5. Do not copy plugins or configuration across directories.

"I fixed it but it still fails" usually means editing the wrong directory. Multiple installs or environments leave similar directories; confirm the effective one.

Create or restore the directory structure from documentation, not by guessing. An empty directory that loads sometimes still produces no providers.

Permissions

Readable is not the same as accessible.

1. Compare the service user with the directory owner.
2. Check read and execute permission on the directory.
3. Check configuration file read permission.
4. Check whether the parent directory blocks traversal.
5. Change only necessary permissions, avoiding 777.

Loose permissions fix symptoms and create risks. Make only the service user able to read; do not open everything.

Containers and services add layers. Mapped volumes and users differ; permission problems on the host may still fail inside.

Format and configuration

Format errors produce explicit parse failures; check fields and types.

1. Compare field names and structure with documentation.
2. Confirm types: strings, arrays, and objects.
3. Check trailing commas and indentation.
4. Validate with a linter or parser where available.
5. Back up before editing.

Hand-edited configuration is error-prone. Use a minimal valid configuration first, then add providers.

Format validation is not semantic validation. Passwords and addresses may still be wrong even when parsing succeeds.

Isolation test

Separating provider problems from plugin conflicts takes two steps.

1. Disable recently installed provider plugins and restart.
2. If the error disappears, it is plugin-related; check compatibility and configuration.
3. If it persists, the directory or configuration itself is the problem.
4. Restore a minimal valid configuration to verify.
5. Re-enable plugins one at a time.

Disabling is not uninstalling. Keep the directory and configuration for later diagnosis.

Record the comparison result. Which change recovered the state is the most useful evidence.

Recovery order

From least destructive to most.

1. Read the log: the full error points to path, permission, or parse.
2. Fix the path: correct the data directory or create the structure.
3. Fix permissions: make only the service user readable.
4. Fix format: restore a minimal valid configuration.
5. Isolate plugins: disable recent ones.
6. Backup and reinstall: only when configuration is corrupted beyond recovery.

Reinstalling last is deliberate. It rarely fixes path and permission issues and may obscure the cause.

Prevention

Three habits reduce recurrence.

1. Record data directory and provider directory locations.
2. Back up configuration before editing.
3. Change one item at a time and verify startup.

Configuration is infrastructure. Records beat guessing.

Next steps

Path, permissions, format. For provider setup, read How to configure models. For missing models, read Model list incomplete. For key errors, read API key invalid and model discovery 404.

Sources: DeepSeek Harness docs, dsh CLI README, deepseek-harness repository