Skip to content
ParseHawkParseHawk Developer Docs

Troubleshoot a local stack

Start with ParseHawk’s own view of the system:

Terminal window
parsehawk status
parsehawk doctor

A service does not start

Section titled “A service does not start”

Read the component logs:

Terminal window
ls data/logs
tail -f data/logs/api.log
tail -f data/logs/worker.log
tail -f data/logs/runtime.log

Then perform a controlled restart:

Terminal window
parsehawk restart

The first runtime start is slower because it downloads model weights, profiles memory, and warms kernels.

A port is already in use

Section titled “A port is already in use”

parsehawk start refuses to hide an unknown process behind a stale or missing state file. Check the standard ports—5173, 8000, 6006, and 8080—and stop the process that owns the conflicting one. Then start ParseHawk again.

The model runtime runs out of memory

Section titled “The model runtime runs out of memory”

Reduce context first:

Terminal window
PARSEHAWK_VLLM_MAX_MODEL_LEN=8192 parsehawk restart

On Linux, also reduce PARSEHAWK_VLLM_MAX_NUM_SEQS or GPU memory utilization. Large PDFs multiply image-token and memory requirements; lower PARSEHAWK_PDF_MAX_PAGES when appropriate.

Jobs remain queued

Section titled “Jobs remain queued”

Check that the worker is healthy and is using the same database and data directory as the API. A healthy API alone cannot process a job. Review data/logs/worker.log for a provider connection or credential error.

A parse job fails

Section titled “A parse job fails”

Check the job’s stable error.code before you retry:

Terminal window
parsehawk parse-jobs get parse_job_...
  • unsupported_input means parsing did not receive a supported PDF, JPEG, or PNG source.
  • page_limit_exceeded means the PDF is larger than PARSEHAWK_PDF_MAX_PAGES.
  • model_modality_incompatible means the selected model does not accept image content.
  • invalid_model_output means one page returned empty or invalid Markdown.
  • parsing_timeout means one page request exceeded the model timeout.

A failure on one page fails the complete parse job. ParseHawk does not return a partial document in the current developer preview.

An external provider is unreachable

Section titled “An external provider is unreachable”
Terminal window
parsehawk providers get openai_compatible_api
parsehawk providers models openai_compatible_api

For a server on the Mac host while ParseHawk runs in Docker, use host.docker.internal, not 127.0.0.1. For Ollama, follow the connection checklist.

Local data was removed while services were running

Section titled “Local data was removed while services were running”

Stop every ParseHawk process before restoring or recreating storage. Processes can keep deleted SQLite files open. If the state file is gone, locate and stop the process holding the API or worker resources before starting again.

Get a clean diagnostic

Section titled “Get a clean diagnostic”

When reporting an issue, include:

  • parsehawk doctor output
  • parsehawk status output
  • host OS, architecture, memory, and GPU
  • the failing component’s log excerpt with secrets and document content removed
  • ParseHawk version or Git commit
  • provider and model names, without API keys