---

name: documenso-debug-bundle description: 'Comprehensive debugging toolkit for Documenso integrations.

Use when troubleshooting complex issues, gathering diagnostic information,

or creating support tickets for Documenso problems.

Trigger with phrases like "debug documenso", "documenso diagnostics",

"troubleshoot documenso", "documenso support ticket".

' allowed-tools: Read, Write, Edit, Bash(curl:), Bash(node:), Grep version: 1.14.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• documenso
• debugging compatibility: Designed for Claude Code

---

Documenso Debug Bundle

Output

• A minimal redacted diagnostic bundle with correlation IDs, lifecycle state, environment, version, and status evidence.
• A safe escalation/recovery record that preserves document/signature confidentiality and audit integrity.

Examples

For a signing failure, collect opaque document/correlation IDs, template version, environment, state transition, callback result, and timestamp. Review the bundle for document content, signer PII, signing links, tokens, and audit payloads before sharing; reproduce only with synthetic documents through the approved incident/support route.

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A' !uname -a

Overview

Comprehensive debugging tools for Documenso integration issues. Includes diagnostic scripts, curl debug commands, environment verification, and support ticket templates.

Prerequisites

• Documenso SDK installed
• Access to logs and configuration
• curl and jq available

Instructions

Step 1: Quick Connectivity Test

#!/bin/bash
set -euo pipefail

echo "=== Documenso Connectivity Test ==="

# 1. Check API key is set
if [ -z "${DOCUMENSO_API_KEY:-}" ]; then
  echo "FAIL: DOCUMENSO_API_KEY not set"
  exit 1
fi
echo "OK: API key set (${#DOCUMENSO_API_KEY} chars)"

# 2. Test authentication
BASE="${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v1}"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1")

if [ "$STATUS" = "200" ]; then
  echo "OK: API authentication successful"
elif [ "$STATUS" = "401" ]; then
  echo "FAIL: Invalid API key (401)"
  exit 1
elif [ "$STATUS" = "403" ]; then
  echo "FAIL: Insufficient permissions (403) — try a team API key"
  exit 1
else
  echo "WARN: Unexpected status $STATUS"
fi

# 3. Check latency
LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1")
echo "Latency: ${LATENCY}s"

# 4. List recent documents
echo "=== Recent Documents ==="
curl -s -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=5" | jq '.documents[] | {id, title, status, createdAt}'

Step 2: TypeScript Diagnostic Script

// scripts/documenso-diagnose.ts
import { Documenso } from "@documenso/sdk-typescript";

async function diagnose() {
  const results: Array<{ test: string; status: "PASS" | "FAIL"; detail: string }> = [];

  // Test 1: API key
  const apiKey = process.env.DOCUMENSO_API_KEY;
  if (!apiKey) {
    results.push({ test: "API Key", status: "FAIL", detail: "DOCUMENSO_API_KEY not set" });
    return results;
  }
  results.push({ test: "API Key", status: "PASS", detail: `Set (${apiKey.length} chars)` });

  // Test 2: Connection
  const client = new Documenso({
    apiKey,
    ...(process.env.DOCUMENSO_BASE_URL && { serverURL: process.env.DOCUMENSO_BASE_URL }),
  });

  try {
    const start = Date.now();
    const { documents } = await client.documents.findV0({ page: 1, perPage: 1 });
    const latency = Date.now() - start;
    results.push({
      test: "Connection",
      status: "PASS",
      detail: `${latency}ms, ${documents.length} documents returned`,
    });
  } catch (err: any) {
    results.push({
      test: "Connection",
      status: "FAIL",
      detail: `${err.statusCode ?? "unknown"}: ${err.message}`,
    });
  }

  // Test 3: Create + Delete (write access)
  try {
    const doc = await client.documents.createV0({ title: "[DIAG] Test Document" });
    await client.documents.deleteV0(doc.documentId);
    results.push({ test: "Write Access", status: "PASS", detail: "Create+delete OK" });
  } catch (err: any) {
    results.push({
      test: "Write Access",
      status: "FAIL",
      detail: err.message,
    });
  }

  // Print report
  console.log("\n=== Documenso Diagnostic Report ===");
  for (const r of results) {
    console.log(`  [${r.status}] ${r.test}: ${r.detail}`);
  }
  const failures = results.filter((r) => r.status === "FAIL").length;
  console.log(`\n${results.length} tests, ${failures} failures\n`);

  return results;
}

diagnose();

Run: npx tsx scripts/documenso-diagnose.ts

Step 3: Debug Logging Wrapper

// src/documenso/debug-client.ts
import { Documenso } from "@documenso/sdk-typescript";

export function createDebugClient(): Documenso {
  const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

  // Proxy to log all method calls
  return new Proxy(client, {
    get(target, prop) {
      const value = (target as any)[prop];
      if (typeof value === "object" && value !== null) {
        return new Proxy(value, {
          get(innerTarget, innerProp) {
            const method = (innerTarget as any)[innerProp];
            if (typeof method === "function") {
              return async (...args: any[]) => {
                const start = Date.now();
                console.log(`[DOCUMENSO] ${String(prop)}.${String(innerProp)}(`, JSON.stringify(args).slice(0, 200), ")");
                try {
                  const result = await method.apply(innerTarget, args);
                  console.log(`[DOCUMENSO] OK in ${Date.now() - start}ms`);
                  return result;
                } catch (err: any) {
                  console.error(`[DOCUMENSO] FAIL in ${Date.now() - start}ms: ${err.statusCode} ${err.message}`);
                  throw err;
                }
              };
            }
            return method;
          },
        });
      }
      return value;
    },
  });
}

Step 4: Support Ticket Template

When filing an issue on GitHub or Discord:

## Environment
- Documenso: Cloud / Self-hosted v[version]
- SDK: @documenso/sdk-typescript v[version]
- Node.js: [version]
- OS: [os]

## Issue Description
[What you expected vs what happened]

## Steps to Reproduce
1. [Step 1]
2. [Step 2]

## API Request (sanitized)
- Method: POST /api/v2/documents
- Status: [HTTP status]
- Response: [error body, no secrets]

## Diagnostic Output
[Paste output from documenso-diagnose.ts]

## Logs
[Relevant log lines, sanitized]

Error Handling

Issue	Cause	Solution
Diagnostic timeout	Slow API or network	Check connectivity, increase timeout
Write test fails	Read-only key or no team access	Use team API key with write permissions
Self-hosted unreachable	Docker container down	docker ps, check container logs
Latency > 5s	Network or infrastructure issue	Check if self-hosted DB is overloaded

Resources

• Documenso GitHub Issues
• Documenso Discord
• Status Page
• API Reference

Next Steps

For rate limit handling, see documenso-rate-limits.