Troubleshoot connection and examination errors
Find the failed step, recover the existing job when possible, and give the operator enough evidence to investigate.
Start with list_surveys. It checks connection and authentication without invoking title models. If you already started a job, save its UUID and use that ID for diagnosis.
Choose the problem
| Symptom | Read |
|---|---|
| The client cannot discover tools | Your agent cannot see the examiner |
| HTTP 401 or an OAuth prompt | Authentication fails |
| Start returns an error | A start request is rejected |
| The client disconnected | Recover the existing run |
| The job failed | Status shows failed |
| A report is missing or partial | Reports are incomplete or unavailable |
| Ownership or acreage conflicts | The numbers look convincing but conflict |
Your agent cannot see the examiner
- Confirm which connection you configured: remote Streamable HTTP or a local stdio bridge. Follow Connect your agent for that path.
- For HTTP, check the operator’s HTTPS endpoint and protected
Authorization: Bearer ...header. The client must support custom headers. - For the bridge, confirm Node.js 22.16 or newer, the configured absolute path, and the kit’s folder structure. Run
npm ci --prefix scriptsfrom the kit root to install its dependency. - Reload or restart the client as its setup instructions require. Keep existing MCP entries when editing its configuration.
- Ask the agent to discover tools and call
list_surveys.
Success: the six tools appear and the survey call succeeds. A running bridge process without a successful tool call does not prove connection.
The bridge reads .env in the kit root, beside scripts/, regardless of your shell’s working directory. The client must launch it on the machine where the kit and Node.js are installed. For a cloud, mobile, or browser-based client without local-process support, use direct HTTP if its MCP integration supports protected custom headers.
| Bridge message | Corrective action |
|---|---|
MCP bridge needs a root .env containing MCP_HTTP_API_KEY. | Create .env in the kit root; check that the filename is not .env.txt. |
Could not parse the root .env file. | Use plain-text dotenv assignments and remove malformed syntax. |
MCP_HTTP_API_KEY is missing or too short. | Confirm the key with the operator. The bridge requires at least 32 characters. |
MCP bridge requires an HTTPS server URL argument or MCP_PUBLIC_URL in the protected environment. | Use the HTTPS endpoint ending in /mcp. |
MCP bridge dependency is missing; run npm ci --prefix scripts in the kit root. | Run the installation command from the extracted kit root, then reconnect. |
Could not start the bridge dependency; check Node.js and reinstall with npm ci --prefix scripts. | Confirm Node.js works and reinstall the dependency from the kit root, then restart the client. |
For a terminal diagnostic, replace the path and endpoint. Use quotes around the script path, especially when the folder contains spaces.
macOS or Linux:
node "/absolute/path/to/title-examiner-tester/scripts/mcp_bridge.mjs" \
https://your-examiner-host/mcp
Windows PowerShell:
node "C:/Users/your-account/Documents/title-examiner-tester/scripts/mcp_bridge.mjs" "https://your-examiner-host/mcp"
The stdio bridge can wait silently for MCP input. Stop this diagnostic with Control+C before letting your client launch its own process. Keep .env and the key out of screenshots and support messages.
Authentication fails
HTTP 401 with authentication required means the service did not accept a bearer credential.
- Verify the endpoint and key with the operator through your private channel.
- For HTTP, update the client’s protected header setting. For the bridge, update the kit’s root
.env. - Reload the connection and call
list_surveysagain.
Success: the authenticated survey call succeeds. The service has no OAuth sign-in; an OAuth-only connector cannot authenticate from the URL alone. Use the direct-header or bridge path instead.
For TLS or network failures, send the operator the hostname, timestamp, and safe error. The operator needs to check routing, certificates, and runtime health. Keep HTTPS enabled.
A start request is rejected
Use the exact error to correct the input or ask the operator for missing prerequisites. These errors do not mean your request joined a queue.
| Error | Meaning and action |
|---|---|
another title examination is already queued or running | The active-job slot is occupied. Poll your saved job or coordinate with the operator. |
driver=agent is disabled for hosted MCP; use driver=bfs | Use bfs on the hosted endpoint. |
docs_dir must be a directory under data/ | Ask the operator to prepare a directory below the server’s project data/. |
docs_dir must be an existing directory | The server directory is absent. A laptop path does not upload files. |
docs_dir must contain at least one PDF | Ask the operator to check that the directory contains lowercase *.pdf files. |
max_docs must be between 1 and 500 | Choose a supported integer and reconsider the possible work/spend before raising it. |
web providers require an explicit positive budget and cost_per_doc | Agree the acquisition estimates with the operator and provide both values. |
allow_purchase requires allow_browser | Purchases require browser sourcing as well as the separate purchase gate. |
browser or purchase opt-in requires browserbase or composite provider | The selected provider cannot use those opt-ins. |
browser sourcing is disabled by this MCP host | Ask the operator whether live sourcing is appropriate; a request cannot change the host gate. |
browser purchase is disabled by this MCP host | Ask the operator about the acquisition plan; repeated starts cannot enable purchases. |
For unregistered cases, supply county and either a prepared server PDF directory or a supported zero-upload request. Only exa and browserbase accept an ad hoc case without a directory, and both require a nonempty seed.
Next step: verify the corrected arguments against the start tool reference. Submit a paid start only when the case and spend remain authorized.
I lost the connection during a run
- Reconnect using the existing MCP configuration.
- Call
get_title_exam_statuswith the UUID you saved from the original start. - Continue polling that ID, or retrieve reports when
reports_ready=true.
Success: you recover the same job ID and its state. The detached worker continues after disconnection. A new start creates a new paid job rather than resuming the old one.
There is no job-list or cancel tool. If you lost the ID or need a job stopped, contact the operator. Closing your client does not stop the worker.
Status shows failed
| Error | What the operator needs to check |
|---|---|
examination worker failed; inspect the host job log | The worker exception and provider/runtime context in the private log |
examination worker stopped | A queued/running record whose matching worker is no longer active |
could not start examination worker | Subprocess launch and host resources |
unknown job_id | Whether the saved ID matches an existing record |
job_id must be a UUID generated by start_title_exam | Whether a name, path, or malformed ID was supplied |
Send the job ID, failing tool, timestamp, state, and exact safe error. Wait for diagnosis before authorizing a replacement run. A provider quota or routing failure is different from an incorrect title conclusion.
Status is running but there is no progress percentage
The service reports durable job state rather than a phase-by-phase feed. docs_read and stop_reason can remain unavailable until a manifest or engine result exists.
Poll the saved job at a reasonable interval, such as 30-60 seconds. If it is unusually slow, ask the operator to inspect the private worker log. A missing count alone does not prove the worker stopped.
Wall time varies with record count, scan quality, provider availability, and portal performance. Historical run duration is not a deadline for your case.
Reports are incomplete or unavailable
- Read
get_title_exam_status, then requestget_title_exam_resultswithartifact="summary". - Check
reports_readyand theartifactsavailability map. - Read only available reports. Preserve
incompletelabels, coverage limits, and QA failures in your review.
current reports are not ready; use get_title_exam_status means current LRS/LOR are not both ready for the stored sourced set. artifact 'validation' is not available can mean optional validation was not requested or produced.
| Signal | Review action |
|---|---|
DEAD_END_RED or UNSOURCED | Identify the unresolved cited predecessor and arrange retrieval with the operator. |
EXTRACTION_FAILED | Check the unreadable scan or obtain a better copy. |
BUDGET_EXHAUSTED | Review available output and the acquisition plan before any paid rerun. |
coverage_limited=true | Record dropped document/depth work; a higher limit needs an agreed plan. |
QA_REVIEW_FAILED | Preserve the incomplete-analysis label and inspect the QA problem. |
[truncated] | Ask the operator for the full private file; the MCP read reached 100,000 bytes. |
Success: you can explain what is available, what remains incomplete, and which evidence is needed next. Available partial reports are useful review material, but they do not remove a gap.
A failed exploratory name search differs from an unresolved concrete citation. Follow Documents and sourcing to avoid inventing a missing deed from every unsuccessful search.
The numbers look convincing but conflict
Compare the same tract, interest class, and record set:
- Check that gross acreage belongs to the subject tract, not the whole deed.
- Trace each proposed owner and fraction to the operative instrument language.
- Separate mineral fee interests from NPRI burdens and life estates.
- For probate, check the decedent’s estate shares and any community-property treatment.
- Compare provenance labels, unresolved citations, and curative requirements.
A mineral sum of one is an arithmetic check, not evidence of a complete legal chain. Deterministic verified and closeable values apply to the supplied calculation. Pipeline reports can retain proposed LLM ownership when the evidence is incomplete.
Faithfulness measures whether values occur in available OCR text. It does not establish correct transcription or title completeness. Treat missing OCR as an abstention, not perfect accuracy.
Use Accuracy and known limits and Review results to prepare source-backed corrections before relying on NMA for a purchase.
Send actionable private feedback
Use the pilot feedback template. Include the task, job ID, page/step, tool or report, row or volume/page, observed result, expected result, and supporting source evidence.
Keep credentials and private records in the channel arranged with the operator. The service cannot save corrections or send feedback. A completed review sheet is a deliverable for the operator, not confirmation that a case has changed.