Troubleshooting

Troubleshooting Guide

Common issues and solutions to help you get the most out of Hamsterlog.

Connection Issues

Logs are not appearing in the dashboard

If your logs aren't showing up, follow these steps:

1. Verify your API key

Check that your API key is correct and not truncated
Make sure there are no extra spaces or newlines
Verify the key exists in your dashboard
Try regenerating a new API key

2. Check network connectivity

Test your connection with a simple cURL command:

curl -X POST https://www.hamsterlog.com/api/log \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key-here",
    "logs": [{
      "log": "Test log",
      "tags": ["test"],
      "timestamp": '$(date +%s000)'
    }]
  }'

3. Check your console for errors

Look for error messages in your application console or logs. Common errors:

401 Unauthorized - Invalid API key
429 Too Many Requests - Rate limit exceeded
Network error - Connection problem

Getting 401 Unauthorized errors

This means your API key is invalid or missing:

// ❌ Wrong - missing or invalid API key
const hamster = new Hamster({
    apiKey: "", // Empty key
    defaultTags: ["app"]
});

// ✅ Correct - valid API key
const hamster = new Hamster({
    apiKey: process.env.HAMSTER_API_KEY, // From environment
    defaultTags: ["app"]
});

Getting 429 Rate Limited errors

You're sending too many requests. Solutions:

Increase batch size (send more logs per request)
Reduce logging frequency
Implement exponential backoff

// Implement retry with exponential backoff
async function sendLogWithRetry(hamster, message, tags, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await hamster.log(message, tags);
        } catch (error) {
            if (error.status === 429 && attempt < maxRetries - 1) {
                const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
                await new Promise(resolve => setTimeout(resolve, delay));
                continue;
            }
            throw error;
        }
    }
}

SDK Issues

console.log() calls not being captured

If the SDK isn't capturing your console calls:

1. Check captureConsole setting

// Make sure captureConsole is enabled
const hamster = new Hamster({
    apiKey: "your-api-key",
    captureConsole: true, // This must be true
    copyToLocalConsole: true
});

2. Initialize before console usage

// ❌ Wrong - console.log() called before initialization
console.log("This won't be captured");

const hamster = new Hamster({
    apiKey: "your-api-key",
    captureConsole: true
});

// ✅ Correct - initialize first
const hamster = new Hamster({
    apiKey: "your-api-key",
    captureConsole: true
});

console.log("This will be captured");

3. Check for console conflicts

Other libraries might override console methods. Initialize Hamsterlog last:

// Import other libraries first
import someOtherLibrary from "other-lib";

// Initialize Hamsterlog last to override console
import { Hamster } from "./hamster-node.js";
const hamster = new Hamster({
    apiKey: "your-api-key",
    captureConsole: true
});

Environment-Specific Issues

Node.js Issues

TypeError: fetch is not defined

This happens in older Node.js versions. Install a fetch polyfill:

npm install node-fetch

// At the top of your file
import fetch from 'node-fetch';
global.fetch = fetch;

// Then use Hamsterlog normally
import { Hamster } from './hamster-node.js';

Deno Issues

Permission errors

Deno requires explicit permissions:

# Required permissions
deno run --allow-net --allow-env your-app.ts

# For specific hosts only
deno run --allow-net=hamsterlog.com --allow-env=HAMSTER_API_KEY your-app.ts

PHP Issues

cURL or allow_url_fopen not available

The PHP SDK requires either cURL or allow_url_fopen. Check your configuration:

<?php
// Check if cURL is available
if (!function_exists('curl_init')) {
    echo "cURL is not available
";
}

// Check if allow_url_fopen is enabled
if (!ini_get('allow_url_fopen')) {
    echo "allow_url_fopen is disabled
";
}

// Check both
if (!function_exists('curl_init') && !ini_get('allow_url_fopen')) {
    echo "Neither cURL nor allow_url_fopen is available
";
    echo "Please enable one of them in your PHP configuration
";
}

Swift Issues

Network requests failing on iOS

Check App Transport Security settings in Info.plist:

<!-- For development only - use HTTPS in production -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Data Issues

Wrong timestamps

Timestamps should be in milliseconds, not seconds:

// ❌ Wrong - seconds
const timestamp = Math.floor(Date.now() / 1000);

// ✅ Correct - milliseconds  
const timestamp = Date.now();

// ✅ Also correct
const timestamp = new Date().getTime();

Tags not appearing or being truncated

Check tag limits:

Maximum 50 tags per log
Maximum 100 characters per tag
Tags should be strings, not objects

// ❌ Wrong - object tags
hamster.log("Message", [{ type: "error" }]);

// ❌ Wrong - too long
hamster.log("Message", ["a".repeat(101)]);

// ✅ Correct
hamster.log("Message", ["error", "database", "connection"]);

Special characters not displaying correctly

Make sure you're using UTF-8 encoding:

// ✅ UTF-8 characters work fine
hamster.log("User: 用户123 logged in", ["auth", "international"]);
hamster.log("Temperature: 25°C", ["sensor", "temperature"]);

Development vs Production

Different behavior between environments

Use environment-specific configurations:

const isDevelopment = process.env.NODE_ENV === 'development';

const hamster = new Hamster({
    apiKey: process.env.HAMSTER_API_KEY,
    defaultTags: [
        "app",
        isDevelopment ? "development" : "production"
    ],
    captureConsole: true,
    copyToLocalConsole: isDevelopment, // Only in development
});