Skip to main content

​
Common Issues

Start by checking whether the question was understood as intended. Ask:
  • “What query did you run?”
  • “Explain what you just calculated”
  • “What filters did you apply?”
Often a slight misunderstanding is easily corrected with clarification. Explicit parameters help — “for all of 2025” or “by individual product, not category.”Data quality can also cause unexpected results. Ask “Are there any data quality issues?” and Zark flags problems it detected during processing.For more guidance, see Tips for Better Results.
Most files process successfully. When processing fails, common causes include:
  • Corrupted files — try re-downloading or re-exporting the file
  • Unsupported format — check Supported Formats for compatible file types
  • Encoding issues — for CSV files, try saving as UTF-8
  • Password-protected PDFs — remove the password before uploading
  • Very low resolution scans — OCR may not work cleanly on low-quality scans
For data files specifically, issues often include inconsistent column counts, special characters that confuse parsing, or unusual delimiters. Re-exporting the file as a clean CSV often resolves the issue.
Response times vary by query complexity:
  • Simple queries (file listing, basic questions) — seconds
  • Data analysis (aggregations, comparisons) — 5-30 seconds
  • Multi-tool plans (research + creation) — 30-120 seconds
  • Media processing (transcription, indexing) — minutes depending on file length
  • Image generation — 10-60 seconds
  • Video generation — 1-5 minutes
If a response is significantly slower than expected, try simplifying the query or breaking it into smaller steps.
Zark’s routing is automatic and usually correct, but occasionally it may misinterpret intent. You can guide it:
  • Be explicit — “Search the web for…” forces Web Search context
  • Reference files — “In my uploaded spreadsheet…” directs to Database Queries
  • Use the API — set tools and tool_choice to control which tools are available
For the API, forcing a specific tool:
{
  "tools": ["database"],
  "tool_choice": "database"
}
If file upload stalls or fails:
  • Check your internet connection
  • Verify the file isn’t corrupted — try opening it locally
  • Check file size — ensure it’s within limits
  • Try a different browser or clear cache
  • For API uploads, verify your API key has the correct permissions
If search returns fewer results than expected:
  • Try different phrasing — semantic search matches by meaning, so rephrase your query
  • Check if files have finished processing — recently uploaded files may still be indexing
  • Be more specific — “budget documents from Q3” is better than “documents”
  • Verify the files exist in the current Space — files are scoped per workspace

​
API Issues

All API requests require the x-api-key header:
curl -H "x-api-key: your_api_key" https://api.zarkai.xyz/v1/storage/files
Common issues:
  • Missing or misspelled header name — must be x-api-key (lowercase)
  • Expired or revoked API key — generate a new one from the console
  • Wrong API key for the workspace
The file ID may be incorrect, or the file may have been deleted. Verify with:
curl https://api.zarkai.xyz/v1/storage/files \
  -H "x-api-key: your_api_key"
This lists all files in the workspace. Check that the file ID matches.
For long-running requests with streaming enabled:
  • Increase your client timeout — some tools (video generation, media processing) take minutes
  • Check for proxy or load balancer timeouts in your infrastructure
  • Ensure your SSE parser handles reconnection gracefully

​
Data Analysis Issues

Ask Zark to check for nulls:
How many rows have null values in the amount column?
Then decide how to handle them:
Sum amount, treating nulls as zero

Average amount, excluding null values
Data inconsistencies often cause grouping issues — “USA”, “usa”, and “United States” create separate groups. Ask:
How many distinct values are in the country column?

Standardize the country column
If numbers are treated as text or dates aren’t recognized:
Show me the schema for this table
Then use Table Workshop to fix types:
Change the date column to datetime format
Need more help? Reach us at support@zarklab.ai.