Common Issues

This page covers the most common issues users encounter. Each entry includes the exact error message, cause, and solution steps.

---

Data Issues

No data appearing in surface

Error: Surface loads but shows "No data" or empty table

Cause:

• Connection not sending data
• Surface not linked to connection
• Time window doesn't contain data

Solution:

1. Check connection status (should show "Connected")
2. Verify surface is linked to the correct connection
3. Try expanding time window: YourTable | where timestamp > ago(7d) | take 10

Related: No Data Showing

---

Data is delayed or stale

Error: Timestamps are old, data arrives in batches

Cause:

• Source batching behavior
• Network latency
• Consumer group contention

Solution:

1. Check source configuration for batching settings
2. Verify network connectivity
3. Use dedicated consumer group for OpenIndustrial

---

Connection Issues

Connection timeout

Error: Connection timeout or Unable to connect to host

Cause:

• Network or firewall blocking connection
• Source unreachable
• DNS resolution issues

Solution:

1. Verify source is accessible from your network
2. Check firewall allows outbound HTTPS (443)
3. Verify DNS can resolve source hostname

Related: Can't Connect

---

Authentication failed

Error: Authentication failed or Invalid credentials

Cause:

• Incorrect connection string
• Expired or rotated keys
• Insufficient permissions

Solution:

1. Re-copy connection string from Azure Portal
2. Regenerate keys if recently rotated
3. Verify policy has required permissions (e.g., ServiceConnect for IoT Hub)

---

Invalid connection string

Error: Connection string is invalid or Invalid format

Cause:

• Truncated connection string
• Wrong connection string type
• Extra whitespace or characters

Solution:

1. Copy the FULL connection string from Azure Portal
2. Use the correct string type (Hub-level, not device-level)
3. Remove any extra spaces or line breaks

---

Query Issues

Query returns empty results

Error: Query executes but returns no rows

Cause:

• Time window too narrow
• Field name typo (case-sensitive)
• Filter too restrictive

Solution:

1. Start with no filters: YourTable | take 10
2. Check field names: YourTable | take 1 | project *
3. Add filters one at a time to find the problem

Related: Query Returns Empty

---

Invalid KQL syntax

Error: Syntax error at position X or Unexpected character

Cause:

• Wrong operators or quotes
• Missing pipe operators
• Incorrect function usage

Solution:

Common Mistake	Fix
Using = instead of ==	Use == for equals
Single quotes 'text'	Use double quotes "text"
Missing | between operations	Add pipe: | where
Wrong date format	Use datetime(2026-01-01)

---

Column not found

Error: Column 'fieldName' not found

Cause:

• Typo in field name
• Field doesn't exist in this table
• Case sensitivity issue

Solution:

1. List all columns: YourTable | take 1 | project *
2. Check exact spelling and case
3. KQL field names are case-sensitive

---

Query timeout

Error: Query exceeded timeout or Query cancelled

Cause:

• Query scanning too much data
• No time filter
• Complex aggregations

Solution:

1. Always start with a time filter: | where timestamp > ago(1h)
2. Reduce time range
3. Add specific filters to reduce data scanned

---

Permission Issues

Permission denied

Error: You don't have permission to access this resource

Cause:

• Insufficient workspace role
• Surface permissions not granted
• API key restrictions

Solution:

1. Contact workspace admin to check your role
2. Request appropriate permissions (Viewer/Editor/Admin)
3. Verify you're in the correct workspace

---

API key invalid

Error: Invalid API key or Unauthorized (401)

Cause:

• Incorrect API key
• Expired token
• Key revoked

Solution:

1. Generate a new API key from workspace settings
2. Check key hasn't been revoked
3. Verify key is copied correctly (no extra spaces)

---

Rate Limit Issues

Rate limit exceeded

Error: Rate limit exceeded or Too many requests (429)

Cause:

• Too many API calls in short period
• Polling too frequently
• Multiple clients hitting same endpoint

Solution:

1. Implement exponential backoff in your client
2. Reduce polling frequency
3. Cache responses where appropriate

Best practice:

Minimum recommended polling interval: 5 seconds
Maximum burst requests: 10 per second

---

Surface Issues

Surface not found

Error: Surface not found or 404 Not Found

Cause:

• Surface deleted or renamed
• Wrong workspace
• Incorrect surface name

Solution:

1. Check workspace for existing surfaces
2. Verify surface name exactly matches
3. Surface may have been renamed - check recent changes

---

Cannot create queries in surface

Error: Interface doesn't allow creating queries

Cause:

• Viewer role (read-only)
• Surface in read-only mode
• No connection linked

Solution:

1. Request Editor or Admin role
2. Check if surface is in maintenance mode
3. Link a connection to the surface first

---

Quick Reference

Error	Likely Cause	Quick Fix
No data	Connection or time filter	Check connection status
Auth failed	Credentials	Re-copy from Azure
Timeout	Firewall/network	Check connectivity
Empty query	Time or filter	Expand time range
Permission denied	Role	Contact admin
429 Too Many	Rate limit	Add delays

---

Still Stuck?

If your issue isn't listed here:

1. Check the FAQ for common questions
2. Try troubleshooting by symptom
3. Ask Azi in the chat panel

---

Related

• FAQ - Common questions
• No Data Showing
• Query Returns Empty
• Can't Connect