Troubleshooting

Solutions for common Pointa issues.

Server Issues

Server not detected

Symptoms:

  • Extension shows "Server not connected"
  • AI tool can't find Pointa MCP

Solutions:

  1. Check server status:

    npx pointa-server status

  2. Start if not running:

    npx pointa-server start

  3. Verify it's accessible:

    curl http://127.0.0.1:4242/health

Port already in use

Symptoms:

  • Server fails to start
  • Error: "Port 4242 is already in use"

Solutions:

  1. Find what's using the port:

    lsof -i :4242

  2. Stop the other process, or use a different port:

    POINTA_PORT=4243 npx pointa-server start

  3. Update Chrome extension and MCP config with new port

Connection refused

Symptoms:

  • "Connection refused" errors
  • Extension can't reach server

Solutions:

  1. Ensure server is running on localhost (127.0.0.1), not a remote address

  2. Check firewall settings aren't blocking local connections

  3. Restart the server:

    npx pointa-server restart

Extension Issues

Extension not working

Symptoms:

  • Sidebar doesn't appear
  • Nothing happens when clicking extension

Solutions:

  1. Verify you're on a local development URL:

    • ✅ http://localhost:3000
    • ✅ http://127.0.0.1:8080
    • ❌ https://example.com

  2. Check if extension is enabled:

    • Go to chrome://extensions
    • Ensure Pointa is enabled

  3. Reload the extension:

    • Click the reload icon on the extension card

  4. Check browser console for errors:

    • Right-click page → Inspect
    • Look for Pointa-related errors

Not on localhost detection

Symptoms:

  • Extension says "Only works on localhost"
  • But you are on localhost

Solutions:

Pointa supports these URLs:

  • localhost (any port)
  • 127.0.0.1 (any port)
  • *.local domains
  • *.test domains

If using a custom domain:

  1. Make sure it resolves to 127.0.0.1
  2. Check your /etc/hosts file

Annotations not appearing

Symptoms:

  • Created annotation but no badge shows
  • Annotation not in sidebar

Solutions:

  1. Refresh the page

  2. Check you're on the same URL where you created it

  3. Verify server is running and connected

  4. Check server data:

    cat ~/.pointa/annotations.json

Badges in wrong positions

Symptoms:

  • Badge covers element content
  • Badges overlap each other

Solutions:

  1. Resize your browser window (badges recalculate)

  2. Scroll the page (badges adjust)

  3. If persistent, the element may have unusual positioning

MCP Issues

MCP connection failed

Symptoms:

  • AI tool shows "MCP connection failed"
  • Pointa tools not available

Solutions:

  1. Verify server is running:

    npx pointa-server status

  2. Check your AI tool's configuration:

    • JSON syntax is valid
    • Path to npx is correct
    • Configuration is saved

  3. Restart your AI tool completely (quit and reopen)

Tools not showing in AI

Symptoms:

  • MCP connected but tools not listed
  • AI doesn't recognize Pointa commands

Solutions:

  1. Check MCP is properly configured in your AI tool

  2. Restart the AI tool after configuration changes

  3. Try asking the AI: "What Pointa tools are available?"

  4. Verify with different transport:

    {
  "mcpServers": {
    "pointa": {
      "url": "http://127.0.0.1:4242/mcp"
    }
  }
}

    (Requires manually starting server first)

AI not reading annotations

Symptoms:

  • AI says "no annotations found"
  • But annotations exist

Solutions:

  1. Check annotations are "pending" status (not "in-review" or "done")

  2. Verify URL filtering isn't too restrictive

  3. Ask AI to read from all URLs: "Check Pointa for annotations on any page"

Data Issues

Lost annotations

Symptoms:

  • Annotations disappeared
  • Data seems reset

Solutions:

  1. Check data file exists:

    ls -la ~/.pointa/

  2. View annotations file:

    cat ~/.pointa/annotations.json

  3. Check archive for completed items:

    cat ~/.pointa/archive.json

Corrupted data

Symptoms:

  • Server won't start
  • "JSON parse error" in logs

Solutions:

  1. Stop server

  2. Backup current data:

    cp ~/.pointa/annotations.json ~/.pointa/annotations.json.bak

  3. Fix JSON syntax or reset:

    echo "[]" > ~/.pointa/annotations.json

  4. Restart server

Performance Issues

Sidebar is slow

Symptoms:

  • Sidebar takes long to open
  • Laggy interactions

Solutions:

  1. Check number of annotations (too many on one page can slow things)

  2. Clear completed annotations (mark as done)

  3. Check browser memory usage

Server using too much memory

Solutions:

  1. Restart the server periodically:

    npx pointa-server restart

  2. Archive old data manually

Getting Help

If these solutions don't work:

  1. Check server logs:

    npx pointa-server logs

  2. Check browser console: Right-click → Inspect → Console tab

  3. Report an issue: GitHub Issues

    Include:

    • Steps to reproduce
    • Error messages
    • Browser/OS version
    • Server logs

Related