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

Symptom	Check in Bundle	Fix
401 on all endpoints	environment.txt shows key NOT SET	Generate OAuth2 token in Lucid Developer Portal > API Tokens
403 on document access	documents.json shows permission error	Token scope missing lucidchart.document.content; regenerate with correct scopes
Data links show stale values	data-links.json shows old lastSynced timestamp	Trigger manual data refresh via Lucidchart UI or PATCH datasource endpoint
Export returns 413	App logs show payload too large	Document exceeds export size limit; split into multiple pages before exporting
Empty document list	documents.json returns empty array	Check LUCID_ACCOUNT_ID scope; token may be scoped to a different team folder
Shape IDs not resolving	pages.json missing expected shapes	Shapes on locked layers are excluded from API; unlock layers or use admin token

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.