Common Issues

This guide covers the most frequently encountered issues when using Alactic AGI, with step-by-step solutions. Issues are organized by category for easy navigation.

Dashboard Access Issues

Cannot Access Dashboard URL

Symptoms:

Browser shows "Connection timed out" or "This site can't be reached"
Dashboard URL doesn't load

Possible Causes & Solutions:

1. VM Not Running

Check VM status:

# Azure CLI
az vm get-instance-view `
  --resource-group <your-rg> `
  --name <vm-name> `
  --query "instanceView.statuses[1].displayStatus" -o tsv

# Should return: "VM running"

If VM stopped:

# Start VM
az vm start --resource-group <your-rg> --name <vm-name>
# Wait 2-3 minutes for services to start

2. Incorrect URL

Verify correct URL from deployment outputs:

Go to Azure Portal → Resource Groups
Click "Deployments" in left sidebar
Click your deployment
Check "Outputs" tab
Copy applicationURL value

3. Firewall Blocking Port 443

Check Network Security Group:

Azure Portal → Resource Groups
Click Network Security Group resource
Click "Inbound security rules"
Verify rule exists for Port 443:
- Port: 443
- Protocol: TCP
- Action: Allow
- Priority: <300

If missing, create rule:

Click "+ Add"
Source: Any (or your IP)
Destination port ranges: 443
Protocol: TCP
Action: Allow
Priority: 100
Name: AllowHTTPS
Click "Add"

4. SSL Certificate Issue

If browser shows SSL warning:

Self-signed certificate expected (default)
Click "Advanced" → "Proceed anyway"
Or install custom certificate (Security Best Practices)

5. DNS Not Propagated (Custom Domain)

If using custom domain:

DNS changes take 1-48 hours to propagate
Use IP address directly: https://<vm-public-ip>
Check DNS propagation: whatsmydns.net

Symptoms:

Enter deployment key on login page
Error: "Invalid deployment key" or "Authentication failed"

Solutions:

1. Verify Correct Key

Get key from Azure Key Vault:

# Azure CLI
az keyvault secret show `
  --vault-name alactic-kv-xxxxx `
  --name deployment-key `
  --query value -o tsv

Or Azure Portal:

Go to Key Vault resource
Click "Secrets"
Click "deployment-key"
Click current version
Click "Show Secret Value"

2. Key Format Issue

Deployment key must be:

Format: ak- followed by 40 alphanumeric characters
No spaces before or after
No line breaks
Case-sensitive

Copy-paste from Key Vault to avoid typos.

3. API Service Not Running

SSH into VM and check:

sudo systemctl status alactic-api

# If not running:
sudo systemctl start alactic-api

# Check logs
sudo journalctl -u alactic-api -n 50

4. Clear Browser Cache

Old session may be cached:

Clear browser cache and cookies
Close all browser windows
Reopen browser
Try logging in again

Document Processing Issues

PDF Upload Fails

Symptoms:

Select PDF file
Upload progress bar appears
Error: "Upload failed" or "Invalid file"

Solutions:

1. File Size Exceeds Limit

Check file size against plan limits:

Free: 50 MB max per file
Pro: 100 MB max per file
Pro+: 100 MB max per file
Enterprise: 500 MB max per file

If too large:

# Check file size
ls -lh document.pdf

# Compress PDF (requires ghostscript)
gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 `
   -dPDFSETTINGS=/ebook -dNOPAUSE -dQUIET -dBATCH `
   -sOutputFile=compressed.pdf document.pdf

2. File Corrupted

Verify PDF is valid:

# Try opening in PDF reader
# Or check with pdfinfo
pdfinfo document.pdf

# If errors, PDF may be corrupted

Fix:

Re-download PDF from original source
Use PDF repair tool
Convert from source format (if available)

3. Storage Quota Exceeded

Check usage:

Dashboard → Settings → Usage Statistics
Check "Storage Used: X / Y MB"

If at limit:

Delete old processed documents
Or upgrade plan for more storage

4. Network Timeout

For large files on slow connection:

Try faster internet connection
Upload during off-peak hours
Use compression (see solution 1)

5. Browser Issue

Try different browser (Chrome, Firefox, Edge)
Disable browser extensions (ad blockers may interfere)
Try incognito/private mode

URL Scraping Fails

Symptoms:

Enter URL
Processing starts
Error: "Failed to scrape URL" or "No content extracted"

Solutions:

1. URL Returns 404 or 403

Verify URL is accessible:

curl -I https://example.com/article

# Check HTTP status code
# 200: OK
# 403: Forbidden
# 404: Not Found

If 403 (Forbidden):

Website blocks automated access
Try alternative source
Contact website owner for API access

If 404 (Not Found):

URL may have changed
Check for redirects
Verify URL is correct

2. JavaScript-Heavy Website

Some sites require JavaScript to load content:

Alactic uses basic HTML parsing
JavaScript-rendered content may not be captured
Alternative: Download page manually, upload as HTML file

3. Paywall or Login Required

Website requires authentication:

Can't scrape content behind paywall
Alternative: Download article as PDF, process PDF instead

4. Website Blocks Scrapers (Rate Limiting)

Website detected automated access and blocked:

Wait 10-15 minutes before retry
Reduce scraping frequency
Contact website for API access or permission

5. URL Format Invalid

Must include protocol:

https://example.com/article
example.com/article (missing protocol)

Add https:// before URL.

Processing Stuck at "Processing..."

Symptoms:

Document shows "Processing..." status
Progress bar stuck at same percentage for >5 minutes
Never completes or fails

Solutions:

1. Wait Longer

Processing times vary:

1-page PDF: 15-30 seconds
10-page PDF: 1-3 minutes
50-page PDF: 5-10 minutes
Very large documents: 15+ minutes

Wait at least 15 minutes before assuming stuck.

2. Refresh Page

Status may not be updating:

Refresh browser (F5 or Ctrl+R)
Check if status updated
If still stuck, proceed to solution 3

3. Check Service Status

SSH into VM:

# Check all services
sudo systemctl status alactic-*

# Check specific services
sudo systemctl status alactic-api
sudo systemctl status alactic-worker

# If worker not running:
sudo systemctl restart alactic-worker

4. Check Processing Queue

May be waiting in queue:

Dashboard → Settings → Usage Statistics
Check "Active Jobs" count
If many jobs queued, wait for earlier jobs to complete

5. Azure OpenAI Throttling

Model API may be rate-limited:

# Check API logs for throttling errors
sudo journalctl -u alactic-worker -n 100 | grep -i "429"

# If seeing 429 errors (rate limit):
# - Wait 10-15 minutes
# - Processing will resume automatically

6. Cancel and Retry

If stuck for >30 minutes:

Click "Cancel" on stuck job
Wait 2-3 minutes
Retry processing same document

Extracted Text is Garbled or Empty

Symptoms:

Processing completes successfully
Extracted text is gibberish, empty, or incomplete

Solutions:

1. Scanned PDF (Image, Not Text)

PDF contains images of text, not searchable text:

Check: Try selecting text in PDF reader
If can't select text, PDF is scanned image
Solution: Use OCR tool first
- Adobe Acrobat: Tools → Recognize Text
- Online: Use OCR.space or similar
- Then upload OCR'd PDF

2. Incorrect Text Encoding

PDF uses non-standard encoding:

Try saving PDF with different encoding in PDF editor
Or extract text manually, save as .txt, process text file

3. PDF Protected or Encrypted

PDF has copy protection:

Remove password/protection in PDF editor
Or print to PDF (creates new unprotected PDF)

4. Complex Layout

Tables, columns, or unusual formatting:

Text may be extracted out of order
Use Deep Analysis mode (better layout understanding)
Or manually restructure document before upload

5. Non-English Characters

Special characters or non-Latin scripts:

GPT-4o mini: Decent but not perfect
Solution: Use GPT-4o (better multilingual support)

Summary Quality is Poor

Symptoms:

Document processed successfully
Summary is vague, incorrect, or misses key points

Solutions:

1. Use Higher Analysis Depth

If using Quick Extract:

Change to Standard Analysis or Deep Analysis
More comprehensive understanding
Better summaries

2. Upgrade Model

If using GPT-4o mini:

Try reprocessing with GPT-4o
Superior reasoning and nuance
See Model Selection Guide

3. Document Too Long

Documents >100 pages may exceed context:

Enable "Content Chunking" option
Processes document in sections
Combines section summaries into overall summary

4. Ambiguous or Technical Content

Highly specialized content:

GPT-4o mini struggles with jargon
Use GPT-4o for better understanding
Or provide glossary in API request (custom prompts)

5. Provide Guidance in Processing Options

For API users, add context:

curl -X POST https://<vm-ip>/api/v1/process \
  -H "X-Deployment-Key: ak-xxxxx" \
  -F "file=@document.pdf" \
  -F "model=gpt-4o" \
  -F "prompt=Summarize this legal contract, focusing on obligations and deadlines"

Performance Issues

Dashboard Loading Slowly

Symptoms:

Dashboard takes >10 seconds to load
Pages feel sluggish

Solutions:

1. VM Underpowered

Free Plan (Standard_B2s) may struggle under load:

Consider upgrading to Pro (Standard_D2s_v3)
More consistent performance
Better for active use

2. Network Latency

VM far from your location:

Check VM region: Azure Portal → VM → Overview
Latency from US to Europe: ~100-150ms
Solution: Deploy VM in region closer to you

3. Browser Performance

Clear browser cache
Close unnecessary tabs
Try different browser
Disable browser extensions

4. Multiple Concurrent Users

If sharing deployment with team:

Consider upgrading plan (more vCPUs)
Or deploy separate instances per user

Processing Taking Longer Than Expected

Symptoms:

Documents taking 2-3x longer to process than estimated

Solutions:

1. Free Plan CPU Burst Credits Depleted

Standard_B2s (Free Plan) uses burst credits:

Check burst credit balance (Azure Portal → VM → Metrics)
Solution: Space out processing (let credits accumulate)
Or upgrade to Pro (consistent performance)

2. Large Document

Very large documents naturally take longer:

100-page PDF: 15-20 minutes normal
Not a bug, expected behavior

3. Deep Analysis Selected

Deep Analysis is slower:

45-90 seconds per document
If speed matters, use Standard Analysis

4. High Azure OpenAI Load

Model API experiencing high demand:

Retry during off-peak hours (early morning UTC)
Or request quota increase (faster processing)

5. Network Connectivity

VM to Azure services latency:

Check VM is in same region as OpenAI resource
Use ping and traceroute to diagnose

Cost and Billing Issues

Higher Costs Than Expected

Symptoms:

Azure bill higher than plan estimates
Unexpected charges

Solutions:

1. Verify Correct Plan Deployed

Check VM SKU:

curl -H Metadata:true \
  "http://169.254.169.254/metadata/instance/compute/vmSize?api-version=2021-01-01&format=text"

# Should return:
# Free: Standard_B2s
# Pro: Standard_D2s_v3
# Pro+: Standard_D4s_v3

If wrong SKU, redeploy correct plan.

2. More Token Usage Than Expected

Check usage:

Dashboard → Settings → Usage Statistics
Review "Token Usage" this month

If high:

Review processed documents (larger than expected?)
Check for unauthorized access (compromised key?)
Use GPT-4o mini instead of GPT-4o (16x cheaper)

3. Leaving VM Running Idle

Infrastructure costs accrue 24/7:

Free: $72/month even if not used
To save costs: Deallocate VM when not needed (dev/test only)
```
az vm deallocate --resource-group <rg> --name <vm-name>
```

4. Cosmos DB Higher Than Expected

Serverless Cosmos DB charges per request:

Check request count in Azure Portal
If high, may have automated process hitting DB frequently

5. Data Transfer Costs

Outbound data transfer charged:

Minimize large downloads
Or use Azure CDN for caching

Quota Exceeded Before Month End

Symptoms:

Error: "Monthly quota exceeded"
Can't process more documents

Solutions:

1. Wait for Quota Reset

Quotas reset on 1st of month (00:00 UTC):

Track usage throughout month
Plan accordingly

2. Delete Old Documents to Free Storage

If storage quota exceeded:

Dashboard → Results
Select old documents
Click "Delete"
Storage freed immediately

3. Upgrade Plan

For permanent solution:

Pro: 100 PDFs + 200 URLs per month
Pro+: 500 PDFs + 1,000 URLs per month
Enterprise: Unlimited

See Plans Overview.

API Issues

API Returns 401 Unauthorized

Symptoms:

API request returns HTTP 401
Error: "Unauthorized" or "Invalid deployment key"

Solutions:

1. Check Deployment Key

Verify key in request header:

curl -v https://<vm-ip>/api/v1/health \
  -H "X-Deployment-Key: ak-xxxxx"

# Check header sent: X-Deployment-Key: ak-xxxxx

2. Key Format

Must be exact format:

Header name: X-Deployment-Key (case-sensitive)
Header value: ak- + 40 alphanumeric characters

3. Check Key is Current

Get current key:

az keyvault secret show `
  --vault-name alactic-kv-xxxxx `
  --name deployment-key `
  --query value -o tsv

Compare to key in your API request.

API Returns 429 Too Many Requests

Symptoms:

API request returns HTTP 429
Error: "Rate limit exceeded"

Solutions:

1. Reduce Request Rate

API rate limits:

10 requests per second
1,000 requests per hour

Solution: Add delay between requests:

import time

for doc in documents:
    process_document(doc)
    time.sleep(0.2)  # 200ms delay = 5 req/sec

2. Implement Exponential Backoff

Retry with increasing delays:

import time
import requests

def process_with_retry(doc, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(API_URL, json=doc)
        
        if response.status_code == 429:
            wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
            time.sleep(wait_time)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

API Response Times Out

Symptoms:

API request hangs for >60 seconds
Connection timeout error

Solutions:

1. Increase Client Timeout

Default timeouts often too short:

import requests

response = requests.post(
    API_URL,
    json=doc,
    timeout=300  # 5 minutes
)

2. Use Async Processing

For large documents, use async API:

# Submit job
curl -X POST https://<vm-ip>/api/v1/process/async \
  -H "X-Deployment-Key: ak-xxxxx" \
  -F "file=@large-document.pdf"

# Returns job_id
{
  "job_id": "job_abc123",
  "status": "queued"
}

# Poll for completion
curl https://<vm-ip>/api/v1/jobs/job_abc123 \
  -H "X-Deployment-Key: ak-xxxxx"

See API Reference.

Getting Additional Help

If your issue isn't covered here or solutions don't work:

1. Check Service Status

SSH into VM:

# Check all service statuses
sudo systemctl status alactic-*

# View recent logs
sudo journalctl -u alactic-api -n 100
sudo journalctl -u alactic-worker -n 100

2. Review Azure Activity Logs

Azure Portal → Resource Group → Activity log

Look for:

Failed operations
Error messages
Resource changes

3. Contact Support

Email: support@alacticai.com

Include:

Deployment ID (Settings → Deployment Information)
Description of issue
Steps to reproduce
Error messages (full text)
Troubleshooting steps already attempted

Response times:

Community plans: 2-3 business days
Enterprise plans: 24 hours (SLA)

4. Community Support

Support Portal: alactic.io/support

Search knowledge base first
Submit support ticket with details
Browse community discussions

Community Forum: community.alactic.ai

Ask questions
Share solutions
Learn from others

Dashboard Access Issues​

Cannot Access Dashboard URL​

Login Fails: "Invalid Deployment Key"​

Document Processing Issues​

PDF Upload Fails​

URL Scraping Fails​

Processing Stuck at "Processing..."​

Extracted Text is Garbled or Empty​

Summary Quality is Poor​

Performance Issues​

Dashboard Loading Slowly​

Processing Taking Longer Than Expected​

Cost and Billing Issues​

Higher Costs Than Expected​

Quota Exceeded Before Month End​

API Issues​

API Returns 401 Unauthorized​

API Returns 429 Too Many Requests​

API Response Times Out​

Getting Additional Help​

Related Documentation​

Dashboard Access Issues

Cannot Access Dashboard URL

Login Fails: "Invalid Deployment Key"

Document Processing Issues

PDF Upload Fails

URL Scraping Fails

Processing Stuck at "Processing..."

Extracted Text is Garbled or Empty

Summary Quality is Poor

Performance Issues

Dashboard Loading Slowly

Processing Taking Longer Than Expected

Cost and Billing Issues

Higher Costs Than Expected

Quota Exceeded Before Month End

API Issues

API Returns 401 Unauthorized

API Returns 429 Too Many Requests

API Response Times Out

Getting Additional Help

Related Documentation