lucidchart-debug-bundle

Lucidchart Debug Bundle

Overview

This debug bundle collects diagnostic evidence from Lucidchart diagramming API integrations for troubleshooting document access, shape rendering, data linking pipelines, and export failures. It captures OAuth token validation, document listing, page metadata, data-linked shape status, and export endpoint availability. The resulting tarball provides support engineers the evidence to diagnose permission errors, stale data links, broken embeds, and export timeouts without requiring direct Lucid account access.

Prerequisites

• curl, jq, tar installed
• LUCID_API_KEY set (OAuth2 bearer token from Lucid developer portal)
• LUCID_ACCOUNT_ID optionally set for account-scoped queries

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-lucidchart-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "API Key: ${LUCID_API_KEY:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Account ID: ${LUCID_ACCOUNT_ID:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"

# API connectivity — user info
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
curl -sf -o "$BUNDLE/api-health.txt" -w "HTTP %{http_code} in %{time_total}s\n" \
  -H "Authorization: Bearer ${LUCID_API_KEY}" \
  -H "Lucid-Api-Version: 1" \
  "https://api.lucid.co/users/me" 2>&1 || echo "UNREACHABLE" > "$BUNDLE/api-health.txt"

# Document listing (first 10)
echo "=== Documents ===" > "$BUNDLE/documents.json"
curl -sf -H "Authorization: Bearer ${LUCID_API_KEY}" \
  -H "Lucid-Api-Version: 1" \
  "https://api.lucid.co/documents?limit=10" \
  >> "$BUNDLE/documents.json" 2>&1 || echo '{"error":"FAILED"}' > "$BUNDLE/documents.json"

# Page metadata for first document
echo "=== Pages ===" > "$BUNDLE/pages.json"
DOC_ID=$(jq -r '.documents[0].documentId // empty' "$BUNDLE/documents.json" 2>/dev/null)
if [ -n "${DOC_ID:-}" ]; then
  curl -sf -H "Authorization: Bearer ${LUCID_API_KEY}" \
    -H "Lucid-Api-Version: 1" \
    "https://api.lucid.co/documents/${DOC_ID}/pages" \
    >> "$BUNDLE/pages.json" 2>&1
else
  echo '{"error":"No documents found"}' > "$BUNDLE/pages.json"
fi

# Data linking status
echo "=== Data Links ===" > "$BUNDLE/data-links.json"
if [ -n "${DOC_ID:-}" ]; then
  curl -sf -H "Authorization: Bearer ${LUCID_API_KEY}" \
    -H "Lucid-Api-Version: 1" \
    "https://api.lucid.co/documents/${DOC_ID}/dataSources" \
    >> "$BUNDLE/data-links.json" 2>&1 || echo '{"error":"DATA_LINKS_FAILED"}' > "$BUNDLE/data-links.json"
else
  echo '{"error":"Skipped — no document"}' > "$BUNDLE/data-links.json"
fi

# Recent logs
echo "=== Recent Logs ===" > "$BUNDLE/app-logs.txt"
tail -100 /var/log/lucid-integration/*.log >> "$BUNDLE/app-logs.txt" 2>/dev/null || echo "No integration logs found" >> "$BUNDLE/app-logs.txt"

# Rate limit status
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI -H "Authorization: Bearer ${LUCID_API_KEY}" \
  -H "Lucid-Api-Version: 1" \
  "https://api.lucid.co/users/me" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"

# Package versions
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i lucid >> "$BUNDLE/deps.txt" || echo "No Lucid npm packages found" >> "$BUNDLE/deps.txt"

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-lucidchart-*.tar.gz
cat debug-lucidchart-*/environment.txt          # Verify API key is set
cat debug-lucidchart-*/api-health.txt           # Check HTTP status and latency
jq '.documents | length' debug-lucidchart-*/documents.json  # Count accessible docs
jq '.dataSources' debug-lucidchart-*/data-links.json        # Check linked data sources

Common Issues

Automated Health Check

async function checkLucidchartHealth(): Promise<{
  status: string;
  latencyMs: number;
  userOk: boolean;
  documentCount: number;
  dataLinkingAvailable: boolean;
}> {
  const apiKey = process.env.LUCID_API_KEY;
  const headers = {
    Authorization: `Bearer ${apiKey}`,
    "Lucid-Api-Version": "1",
  };
  const start = Date.now();

  const userRes = await fetch("https://api.lucid.co/users/me", { headers });
  const docsRes = await fetch("https://api.lucid.co/documents?limit=1", { headers });

  let documentCount = 0;
  let dataLinkingAvailable = false;
  if (docsRes.ok) {
    const data = await docsRes.json();
    documentCount = data.documents?.length ?? 0;
    if (documentCount > 0) {
      const docId = data.documents[0].documentId;
      const dlRes = await fetch(
        `https://api.lucid.co/documents/${docId}/dataSources`, { headers }
      );
      dataLinkingAvailable = dlRes.ok;
    }
  }

  return {
    status: userRes.ok ? "healthy" : "degraded",
    latencyMs: Date.now() - start,
    userOk: userRes.ok,
    documentCount,
    dataLinkingAvailable,
  };
}

Resources

• Lucid Developer Portal
• Lucid Status Page
• Lucid API Changelog

Next Steps

See lucidchart-rate-limits.