Skip to main content

​
Common Issues

​
Authentication Issues

​
Cannot Find Developer Token

Problem: You don’t know where to find your API key/developer token. Solution: Generate a developer token from your Aden dashboard:
  1. Log in to your Aden Dashboard
  2. Go to Settings > API Keys
  3. Click on Generate New Key
  4. Copy the key immediately and store it securely
For detailed instructions, see Generate Developer Token.
Store your API key in a .env file:
ADEN_API_KEY=your-api-key-here
ADEN_API_URL=https://kube.acho.io
Then load it in your application:
import "dotenv/config";

​
Installation Issues

​
Package Not Found

Problem: npm install aden-ts fails or package is not found. Solution:
  1. Ensure you’re using Node.js 18.0.0 or higher:
node --version
  1. Clear npm cache and try again:
npm cache clean --force
npm install aden-ts
  1. Check your npm registry:
npm config get registry
# Should be: https://registry.npmjs.org/

​
Peer Dependency Warnings

Problem: Getting peer dependency warnings when installing aden-ts. Why this happens: The SDK has peer dependencies on LLM provider SDKs (like openai, @anthropic-ai/sdk). You only need to install the ones you’re actually using. Solution: Install the provider SDKs you need: 
# For OpenAI
npm install openai

# For Anthropic
npm install @anthropic-ai/sdk

# For Google Gemini
npm install @google/generative-ai

# Or install all at once
npm install openai @anthropic-ai/sdk @google/generative-ai

​
Module Resolution Errors

Problem: Getting errors like Cannot find module 'aden-ts' or Module not found. Solution:
  1. For TypeScript projects, ensure your tsconfig.json has correct module resolution:
{
  "compilerOptions": {
    "moduleResolution": "bundler",  // or "node16", "nodenext"
    "esModuleInterop": true
  }
}
  1. For CommonJS projects, use require():
const { instrument, createConsoleEmitter } = require("aden-ts");
  1. For ESM projects, ensure you’re using import:
import { instrument, createConsoleEmitter } from "aden-ts";

​
Instrumentation Issues

​
No Metrics Being Captured

Problem: After calling instrument(), no metrics are being emitted. Solution:
  1. Verify you’re calling instrument() BEFORE creating SDK clients:
// ✅ Correct order
import { instrument, createConsoleEmitter } from "aden-ts";
import OpenAI from "openai";

await instrument({
  emitMetric: createConsoleEmitter({ pretty: true }),
  sdks: { OpenAI },
});

const client = new OpenAI();  // Create client AFTER instrumentation

// ❌ Incorrect order
import OpenAI from "openai";
const client = new OpenAI();  // Too early!

import { instrument } from "aden-ts";
await instrument({ sdks: { OpenAI } });  // Too late!
  1. Check that you’re passing the SDK class to instrument():
// ✅ Correct - pass the class
import OpenAI from "openai";
await instrument({ sdks: { OpenAI } });

// ❌ Incorrect - passing an instance
const client = new OpenAI();
await instrument({ sdks: { OpenAI: client } });  // Wrong!
  1. Verify your emitter is configured. Use createConsoleEmitter() for debugging:
import { createConsoleEmitter } from "aden-ts";

await instrument({
  emitMetric: createConsoleEmitter({ pretty: true }),
  sdks: { OpenAI },
});

​
TypeScript Type Errors

Problem: Getting TypeScript errors when using the SDK. Solution:
  1. Ensure you’re using TypeScript 5.0.0 or higher:
npx tsc --version
  1. Update your tsconfig.json:
{
  "compilerOptions": {
    "target": "ES2020",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true  // Add this if getting errors in node_modules
  }
}
  1. If using import types, ensure proper syntax:
import type { MeterOptions, MetricEmitter } from "aden-ts";

​
Instrumentation Not Working in Production

Problem: Instrumentation works locally but not in production/deployed environment. Checklist:
  1. Environment variables: Ensure ADEN_API_KEY is set in production
  2. Build process: Verify the SDK is included in your production bundle
  3. Initialization timing: Ensure instrument() is called before SDK clients are created
  4. Network access: Verify your production environment can reach kube.acho.io

​
Runtime Issues

​
Top-level await Error

Problem: Getting errors like SyntaxError: await is only valid in async functions. Why this happens: You’re using await instrument() at the top level, but your environment doesn’t support top-level await. Solution: Use an async IIFE (Immediately Invoked Function Expression): 
import { instrument, createConsoleEmitter } from "aden-ts";
import OpenAI from "openai";

(async () => {
  await instrument({
    emitMetric: createConsoleEmitter({ pretty: true }),
    sdks: { OpenAI },
  });

  // Your application code here
  const client = new OpenAI();
  // ...
})();
Or use .then(): 
instrument({
  emitMetric: createConsoleEmitter({ pretty: true }),
  sdks: { OpenAI },
}).then(() => {
  // Your application code here
  const client = new OpenAI();
  // ...
});

​
Streaming Not Working

Problem: Streaming responses are not being tracked or metrics are incomplete. Solution:
  1. Ensure you’re fully consuming the stream:
const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
  stream: true,
});

// ✅ Correct - consume all chunks
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

// ❌ Incorrect - breaking early prevents metric emission
for await (const chunk of stream) {
  if (chunk.choices[0]?.delta?.content) {
    break;  // Stops consuming stream
  }
}
  1. Handle stream errors properly:
try {
  for await (const chunk of stream) {
    // Process chunk
  }
} catch (error) {
  console.error("Stream error:", error);
}

​
Connection Issues

​
Cannot Connect to Control Server

Problem: SDK cannot connect to the Aden control server at kube.acho.io. Checklist:
  1. Verify API Key: Ensure ADEN_API_KEY environment variable is set correctly
  2. Check Network: Verify you can reach the server: 
    curl -I https://kube.acho.io
  3. Firewall: Check if your firewall or corporate proxy is blocking the connection
  4. SSL/TLS: Ensure your Node.js installation supports modern TLS (Node.js 18+ recommended)
Workaround: Use failOpen: true (default) to allow requests even if server is unreachable: 
await instrument({
  apiKey: process.env.ADEN_API_KEY,
  serverUrl: "https://kube.acho.io",
  failOpen: true,  // Requests proceed even if control server is down
  sdks: { OpenAI },
});

​
Timeout Errors

Problem: Requests to the control server are timing out. Solution:
  1. Check your internet connection
  2. Verify the control server status
  3. If behind a proxy, configure proxy settings:
// Set proxy via environment variables before running your app
process.env.HTTPS_PROXY = "http://proxy.example.com:8080";
process.env.HTTP_PROXY = "http://proxy.example.com:8080";

​
Framework-Specific Issues

​
Vercel AI SDK Not Tracking

Problem: Using Vercel AI SDK but metrics aren’t being captured. Solution: Vercel AI SDK requires fetch instrumentation. Ensure you’re instrumenting before importing: 
import { instrument } from "aden-ts";
import OpenAI from "openai";

await instrument({ sdks: { OpenAI } });

// Now import Vercel AI SDK
import { streamText } from "ai";

​
Next.js Module Errors

Problem: Getting module resolution errors in Next.js applications. Solution:
  1. For Next.js 13+ with App Router, ensure you’re using Server Components for instrumentation:
// app/layout.tsx (Server Component)
import { instrument } from "aden-ts";
import OpenAI from "openai";

await instrument({ sdks: { OpenAI } });

export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>;
}
  1. Add to next.config.js if needed:
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['aden-ts'],
  },
};

module.exports = nextConfig;

​
Getting Help

If you’re still experiencing issues:

GitHub Issues

Report bugs or request features

Documentation

Review the SDK documentation
When reporting issues, please include:
  • Node.js version (node --version)
  • TypeScript version (if applicable): npx tsc --version
  • aden-ts version: npm list aden-ts
  • Package manager (npm, yarn, pnpm, bun)
  • Operating system
  • Minimal code example that reproduces the issue
  • Full error message and stack trace