FactVerse AI Agent Troubleshooting

Use this guide when an AI client connects to FactVerse AI Agent but the workflow cannot complete as expected. Start with the endpoint, API key, scope, and source-data boundary before investigating workflow logic.

Quick triage order

1. Confirm the client is using the expected host and endpoint.
2. Confirm the request sends X-API-Key.
3. List tools at runtime and compare the visible tools with the expected workflow.
4. Confirm the API key scopes match the tool scopes.
5. Check source data freshness, asset mapping, document availability, and scene version.
6. Check approval policy before investigating blocked write actions.

Connection and authentication

Symptom	Likely cause	Check	Fix
Gateway returns 403	API key header is missing	Inspect request headers	Send the key with X-API-Key
Gateway returns 401	Key is invalid, revoked, expired, or for another environment	Ask the administrator to confirm key status	Rotate or reissue the key
Client connects to the wrong route	Endpoint path or host is incorrect	Compare the route with /mcp/base/, /mcp/pdm/, or the enabled module endpoint	Update the client server URL
TLS or network failure	Client cannot reach the customer host	Test the host from the same network	Fix network, proxy, DNS, or certificate trust

Tool visibility and scope

Symptom	Likely cause	Check	Fix
Expected tool is missing	Wrong endpoint, module disabled, or key lacks scope	Run runtime tool discovery	Use the correct endpoint or request the required scope
Scope denied	Key scope is below the tool requirement	Compare the tool scope with the scope reference	Update key policy through the administrator
Tool list is empty	Endpoint is reachable but module configuration is unavailable	Check deployment module enablement	Enable the module or use a supported endpoint
Write tool is hidden	Key is read-only or approval policy blocks write tools	Check base.action.write and workflow policy	Keep output as a draft until write access is approved

Data and asset issues

Symptom	Likely cause	Check	Fix
Asset cannot be resolved	Name or ID differs across Platform, Inspector, DFS, and documents	Search by site, area, equipment ID, and aliases	Update asset mapping after confirmation
Answer is vague	Source data is missing, stale, or too broad	Check data timestamps and query boundary	Narrow the boundary or repair the data pipeline
Recent work is missing	Inspector or external work-order records are not synchronized	Check latest sync time and source-system status	Refresh the connector and rerun
Documents are unavailable	Document is outside tenant, permission, or knowledge scope	Check document permissions and tenant assignment	Update document access or attach the correct source

Predictive maintenance issues

Symptom	Likely cause	Check	Fix
Health summary is weak	Signal history is short, sparse, or unmapped	Review signal duration, sampling interval, units, and gaps	Return a data-readiness report and repair input data
Anomaly lacks explanation	Maintenance context or operating mode is missing	Compare anomaly window with work history and mode changes	Attach work records, inspection notes, and operating state
Too many alerts	Asset group or threshold configuration is too broad	Review asset boundary and threshold policy	Tune with the maintenance engineer
Follow-up action is blocked	Engineer review or write scope is missing	Check approval state and base.action.write	Keep the action as a draft

Physical AI and simulation issues

Symptom	Likely cause	Check	Fix
Scene cannot be used for simulation	Scene version or required asset metadata is missing	Check scene version, asset versions, scale, and coordinate system	Prepare a scenario package before compute
Simulation behaves poorly	Collision, mass, articulation, friction, or constraint metadata is incomplete	Run a SimReady readiness review	Repair metadata and rerun readiness checks
Result cannot be reused	Assumptions, backend parameters, or validation notes are missing	Inspect scenario package and result record	Add assumptions, limitations, and validation notes
Compute request is blocked	Compute scope or owner approval is missing	Check base.compute.run and project approval	Route the request to the engineering owner

Escalation record

When a problem needs product or implementation support, capture this record:

Field	Description
Environment	Host, endpoint, tenant or project identifier, and deployment type.
Request	User task, time range, asset or scene boundary, and client type.
Tool discovery	Visible tools, missing expected tools, and scopes held by the key.
Source status	Asset mapping, data freshness, document availability, scene version, and connector state.
Error	HTTP status, tool error, validation message, or blocked approval state.
Review owner	Operator, maintenance engineer, engineering owner, or administrator responsible for the next decision.