Chat troubleshooting

This page helps you diagnose and resolve common problems in Ivy -- streaming failures, tool errors, citation issues, and response quality problems. Turn to it when a conversation behaves unexpectedly and you want to know whether the cause is transient or something you can fix. Each section pairs the symptoms you'd see with the steps to recover.

Troubleshooting

This page covers common issues you may encounter in Ivy and how to resolve them.

Streaming failures

Response stops mid-stream

Symptoms: The AI response cuts off abruptly, the streaming indicator disappears, and no error message is shown.

Causes and solutions:

1. Network interruption -- Check your internet connection. The platform attempts to reconnect automatically. If the response does not resume within a few seconds, refresh the page. Your message history is preserved.

2. Context limit reached -- If the context usage indicator was in the amber or red zone, the model may have hit its token limit. Start a new chat and summarize key findings from the previous conversation.

3. Server timeout -- Long-running responses may time out after extended periods. Try simplifying your query or breaking it into smaller steps.

Response takes too long to start

Symptoms: After submitting a query, there is no visible response for 10+ seconds.

Causes and solutions:

1. Extended thinking is active -- If thinking mode is set to On or Auto, the AI may spend several seconds reasoning before it begins streaming. The thinking indicator (brain icon) should be visible during this phase. This is normal for complex queries.

2. Provider congestion -- AI model providers occasionally experience high load. The orchestrator has automatic fallback to alternative providers. Wait up to 30 seconds before retrying.

3. Tool pre-processing -- If the AI is preparing to execute a tool (e.g., validating a protein sequence), there may be a brief delay before the response begins.

Tool call errors

Tool fails to execute

Symptoms: The tool call card shows a red error status with an error message.

Common errors:

Tool returns unexpected results

Symptoms: The tool completes successfully, but the results do not match expectations.

Steps to diagnose:

1. Expand the tool call card and verify the Parameters section. Confirm the AI passed the correct inputs.
2. Check if the correct tool was selected. For example, the AI might have run a substructure search when you wanted a similarity search. Rephrase your query to be more specific.
3. Review the tool's documentation page for input requirements and limitations.

Tool call stuck in "running" state

Symptoms: The tool call card shows a spinning indicator indefinitely.

Solutions:

1. Check the Active Jobs section in the action rail. If the job appears there, it is still processing on the backend.
2. For long-running jobs (e.g., molecular dynamics, large BLAST searches), processing can take several minutes. The job completion notification will alert you when it finishes.
3. If the job has been running for an unusually long time, open the job detail window from the action rail and check the logs for errors.
4. As a last resort, refresh the page. Job state is persisted server-side and will not be lost.

Citations not appearing

No citations at the bottom of a message

Causes and solutions:

1. Response does not reference databases -- Citations are only extracted when the AI includes links that match a known source pattern (for example UniProt, PubChem, NCBI Gene, PubMed, ChEMBL, ClinicalTrials.gov, or RCSB PDB). If the response discusses general concepts without specific database references, no citations will appear.

2. Backend resolution timed out -- The backend citation resolver has a 3-second timeout. If the external APIs (NCBI, PubChem) are slow or unreachable, some entity-name-based citations may not be resolved. Client-side URL-based citations should still appear.

3. Response is still streaming -- Backend citation injection happens after the stream completes. Wait for the streaming indicator to disappear before checking for citations.

Citations link to the wrong entity

Cause: The backend resolver matched an entity name (e.g., "P53") to the wrong database record.

Solution: This is a best-effort system. Click the citation to verify the target. If the link is incorrect, you can search the database directly using the entity name. Consider using the Technical response style, which encourages the AI to include explicit database identifiers (e.g., UniProt accession P04637) rather than gene names.

Response quality issues

Response is too vague or generic

Solutions:

1. Switch the response style to Detailed or Technical for more substantive answers.
2. Provide more context in your query. Instead of "Tell me about BRCA1," try "What are the known druggable binding sites on BRCA1 and which PDB structures cover them?"
3. Enable thinking mode (On) to give the AI more reasoning budget for complex queries.

Response is too long

Solutions:

1. Switch the response style to Concise for shorter, focused answers.
2. Ask more targeted questions instead of broad exploratory ones.

AI selects the wrong tool

Solutions:

1. Name the tool explicitly in your query: "Use DiffDock to dock aspirin into PDB 4HJO."
2. If the AI consistently misidentifies your intent, provide the tool category: "Run a molecular docking analysis (not a similarity search) for..."
3. Check the Tools panel in the action rail to browse available tools and their descriptions.

Canvas card issues

Card not appearing after tool completion

Causes:

1. Auto-canvas disabled -- Check if auto-canvas is enabled in settings.
2. Unsupported tool type -- Some tools do not have canvas card registry entries and produce results only in the chat message.
3. Card dismissed -- You may have previously dismissed the card. Check the tool result in the chat message and re-add it to the canvas.

Card shows "No data"

Cause: The tool returned an empty or malformed result. Expand the tool call card in the chat message and inspect the raw output. If the tool errored silently, the result may be empty.

Performance issues

Workspace feels slow

Solutions:

1. Too many canvas cards -- Dismiss or collapse cards you are not actively using. Each expanded card with an interactive viewer (Tier 2 and above) consumes rendering resources.
2. Long conversation -- Start a new chat when the context indicator approaches the red zone. Long conversations slow down both the AI and the browser.
3. Multiple floating windows -- Close floating windows you are not using. Each window maintains its own renderer.
4. Browser memory -- Check your browser's task manager for memory usage. Close other tabs if needed.

Getting help

If the issue persists after trying the solutions above:

1. Open the Help & Support panel from the action rail.
2. Check the documentation for tool-specific troubleshooting pages.
3. Contact support at [email protected] with details about the issue, including the chat ID and any error messages.