Documenso Debug Bundle
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 ==="
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)"
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
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"
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
import { Documenso } from "@documenso/sdk-typescript";
async function diagnose() {
const results: Array<{ test: string; status: "PASS" | "FAIL"; detail: string }> = [];
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)` });
const client = new Documenso({
apiKey,
...(process.env.DOCUMENSO_BASE_URL && { serverURL: process.env.DOCUMENSO_BASE_URL }),
});
try {
const start = Date.();
{ documents } = client..({ : , : });
latency = .() - start;
results.({
: ,
: ,
: ,
});
} (: ) {
results.({
: ,
: ,
: ,
});
}
{
doc = client..({ : });
client..(doc.);
results.({ : , : , : });
} (: ) {
results.({
: ,
: ,
: err.,
});
}
.();
( r results) {
.();
}
failures = results.( r. === ).;
.();
results;
}
();
Run: npx tsx scripts/documenso-diagnose.ts
Step 3: Debug Logging Wrapper
import { Documenso } from "@documenso/sdk-typescript";
export function createDebugClient(): Documenso {
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
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] .(`, .(args).(, ), );
{
result = method.(innerTarget, args);
.();
result;
} (: ) {
.();
err;
}
};
}
method;
},
});
}
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
Next Steps
For rate limit handling, see documenso-rate-limits.
