Troubleshooting Knowledge Transformer

Learn how to diagnose and resolve issues with Knowledge Transformer.

The troubleshooting guidance covers connection problems, file handling errors, API authentication issues, and other operational challenges you might encounter. Each issue includes a problem description and step-by-step solutions. If you cannot resolve an issue using these procedures, check the API logs for additional diagnostic information or contact your system administrator for assistance.

API not running

Problem

Cannot connect to the API. The system displays a "connection refused" error.

Solutions

Verify that the API is running:
```
curl [your-api-url]/health
```
Check your API URL configuration:
```
zassist transform config show
```
Update the API URL if needed:
```
zassist transform config [new-api-url]
```

Configuration not persisting

Problem

The API URL configuration does not persist across terminal sessions.

Solutions

Check the current configuration:
```
zassist transform config show
```

Re-configure the API URL:

zassist transform config http://localhost:8080

Verify the configuration file exists at ~/.zassist/config.json.
Manually override the API URL for the current session:
```
export TRANSFORM_API_URL="http://localhost:8000"
```

"Unknown command" error

Problem

The CLI does not recognize the command you entered.

Solutions

Use transform, not upload.
When running from the cli/ directory, include the ./ prefix:
```
./zassist transform document.pdf ./knowledge
```
If installed to your system PATH, run without the ./ prefix:
```
zassist transform document.pdf ./knowledge
```

Examples

Correct usage:

./zassist transform document.pdf ./knowledge

Incorrect usage:

zassist upload document.pdf

"File not found" error

Problem

The specified file does not exist.

Solutions

Check the file path is correct.
Use absolute paths or ensure that you are in the correct directory.
Verify file permissions.

Processing timeout

Problem

The transformation process times out before completing.

Solutions

Increase the timeout value using the --timeout flag (default is 30 minutes):
```
zassist transform large-file.vtt ./knowledge --timeout 60m
```

For very large files, use a longer timeout:

zassist transform huge-file.vtt ./knowledge -t 2h

"Failed to create context blob" error

Problem

Cannot create the ZIP file.

Solutions

Check disk space.
Verify write permissions in the current directory.
Ensure input files are accessible.

API returns error

Problem

API rejects the request.

Solutions

Check API logs for details.
Verify the context blob structure (should have input/ and knowledge/ directories).
Check API documentation at [your-api-url]/docs

"401 Unauthorized" or "403 Forbidden" error

Problem

API key authentication failed.

Solutions

Check if the API requires authentication (look for SECURE MODE ENABLED in API logs).

Set the API key:

export TRANSFORM_API_KEY=[your-api-key-here]

Verify the API key is correct.
Ensure the API key environment variable is set in your current session.
Check if the API key matches the one configured on the API server.

Example

Set the API key:

export TRANSFORM_API_KEY=[your-api-key-here]

Verify it is set:

echo $TRANSFORM_API_KEY

Run the transform command:

zassist transform document.vtt ./knowledge

"Unsupported file type" error

Problem

The CLI reports that one or more files have unsupported file types.

Solutions

Check the list of supported file formats displayed in the error message.
Remove unsupported files from your input directory.
Convert unsupported files to a supported format. For more information about supported formats, see Supported file formats.

Example

Error message:

❌ Error: Found 1 unsupported file(s)

Unsupported files:
  • spreadsheet.xlsx (.xlsx not supported)

Supported formats: .docx, .md, .mp4, .pdf, .pptx, .txt, .vtt

Please remove or convert unsupported files and try again.