Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/adobe-advanced-troubleshooting/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill adobe-advanced-troubleshooting. Copyright stays with the author (MIT).

Adobe Advanced Troubleshooting

Overview

Deep debugging techniques for complex Adobe API issues that resist standard troubleshooting: IMS token problems, Firefly async job failures, PDF Services edge cases, and network-layer diagnostics.

Prerequisites

• Access to production logs and metrics
• curl with verbose mode for HTTP debugging
• Understanding of OAuth 2.0 token flows
• Network capture tools (tcpdump, openssl s_client)

Instructions

Technique 1: IMS Token Introspection

When auth issues occur, decode the access token to check claims:

# Adobe IMS tokens are JWTs — decode the payload (middle segment)
TOKEN=$(curl -s -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
  -d "client_id=${ADOBE_CLIENT_ID}&client_secret=${ADOBE_CLIENT_SECRET}&grant_type=client_credentials&scope=${ADOBE_SCOPES}" | jq -r '.access_token')

# Decode JWT payload (base64url-decode the middle segment)
echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .

# Look for:
# - "exp": expiration timestamp (is it expired?)
# - "iss": should be "ims-na1.adobelogin.com"
# - "as": scopes granted (do they match what you requested?)
# - "client_id": verify it matches your ADOBE_CLIENT_ID

Technique 2: Verbose HTTP Request Tracing

# Full HTTP trace against Firefly API
curl -v -X POST 'https://firefly-api.adobe.io/v3/images/generate' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-api-key: ${ADOBE_CLIENT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test","n":1,"size":{"width":512,"height":512}}' 2>&1 | tee firefly-debug.log

# Check for:
# - TLS handshake issues (look for SSL/TLS lines)
# - Request headers actually sent
# - Response headers (Retry-After, x-request-id, x-adobe-*)
# - Response body with error details

Technique 3: Firefly Async Job Failure Analysis

// When async Firefly jobs fail, the status endpoint returns error details
async function diagnoseFireflyJob(jobId: string) {
  const token = await getAccessToken();

  const response = await fetch(
    `https://firefly-api.adobe.io/v3/images/jobs/${encodeURIComponent(jobId)}`,
    {
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-api-key': process.env.ADOBE_CLIENT_ID!,
    },
    }
  );

  const status = await response.json();

  console.log('=== Firefly Job Diagnosis ===');
  console.log('Job ID:', jobId);
  console.log('Status:', status.status);

  if (status.status === 'failed') {
    console.log('Error code:', status.error?.code);
    console.log('Error message:', status.error?.message);
    console.log('Error details:', JSON.stringify(status.error?.details, null, 2));

    // Common failure reasons:
    // - "content_policy": prompt violated guidelines
    // - "input_validation": invalid parameters
    // - "internal_error": Adobe server issue (retry)
    // - "timeout": job took too long (simplify prompt)
  }

  // Log all response headers for Adobe support
  console.log('Response headers:', Object.fromEntries(response.headers.entries()));
}

Technique 4: PDF Services Error Code Mapping

// src/adobe/pdf-error-map.ts
// Comprehensive PDF Services error codes and recovery actions

const PDF_ERROR_MAP: Record<string, { cause: string; action: string; retryable: boolean }> = {
  'DISQUALIFIED':      { cause: 'File is encrypted/password-protected', action: 'Decrypt PDF first', retryable: false },
  'BAD_PDF':           { cause: 'Corrupted or invalid PDF', action: 'Validate with pdfinfo/pdftk', retryable: false },
  'BAD_PDF_CONTENT':   { cause: 'PDF content is malformed', action: 'Re-export from source', retryable: false },
  'UNSUPPORTED_MEDIA_TYPE': { cause: 'Wrong file format for operation', action: 'Check MimeType matches file', retryable: false },
  'FILE_SIZE_EXCEEDED': { cause: 'File exceeds size limit', action: 'Compress or split PDF', retryable: false },
  'PAGE_LIMIT_EXCEEDED': { cause: 'Too many pages for operation', action: 'Split into smaller PDFs', retryable: false },
  'QUOTA_EXCEEDED':    { cause: 'Monthly transaction limit hit', action: 'Upgrade plan or wait for reset', retryable: false },
  'INTERNAL_ERROR':    { cause: 'Adobe server error', action: 'Retry with backoff', retryable: true },
  'TIMEOUT':           { cause: 'Processing timeout', action: 'Try smaller file or fewer pages', retryable: true },
};

export function diagnosePdfError(errorCode: string): string {
  const info = PDF_ERROR_MAP[errorCode];
  if (!info) return `Unknown PDF Services error: ${errorCode}`;
  return `${errorCode}: ${info.cause}\nAction: ${info.action}\nRetryable: ${info.retryable}`;
}

Technique 5: Layer-by-Layer Isolation

#!/bin/bash
# adobe-layer-test.sh — Test each network layer independently

echo "=== Layer 1: DNS Resolution ==="
nslookup ims-na1.adobelogin.com
nslookup firefly-api.adobe.io
nslookup image.adobe.io

echo ""
echo "=== Layer 2: TCP Connectivity ==="
for host in ims-na1.adobelogin.com firefly-api.adobe.io image.adobe.io; do
  timeout 5 bash -c "echo > /dev/tcp/$host/443" 2>/dev/null && echo "$host:443 OPEN" || echo "$host:443 BLOCKED"
done

echo ""
echo "=== Layer 3: TLS Handshake ==="
for host in ims-na1.adobelogin.com firefly-api.adobe.io; do
  echo | openssl s_client -connect "$host:443" -servername "$host" 2>/dev/null | grep -E "subject|issuer|Verify return"
done

echo ""
echo "=== Layer 4: IMS Authentication ==="
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
  'https://ims-na1.adobelogin.com/ims/token/v3' \
  -d "client_id=${ADOBE_CLIENT_ID}&client_secret=${ADOBE_CLIENT_SECRET}&grant_type=client_credentials&scope=${ADOBE_SCOPES}")
echo "IMS Token: HTTP $HTTP_CODE"

echo ""
echo "=== Layer 5: API Endpoint ==="
if [ "$HTTP_CODE" = "200" ]; then
  TOKEN=$(curl -s -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
    -d "client_id=${ADOBE_CLIENT_ID}&client_secret=${ADOBE_CLIENT_SECRET}&grant_type=client_credentials&scope=${ADOBE_SCOPES}" | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
  API_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
    'https://firefly-api.adobe.io/v3/images/generate' \
    -H "Authorization: Bearer $TOKEN" \
    -H "x-api-key: $ADOBE_CLIENT_ID" \
    -H "Content-Type: application/json" \
    -d '{"prompt":"test","n":1,"size":{"width":512,"height":512}}')
  echo "Firefly API: HTTP $API_CODE"
fi

Technique 6: Extract x-request-id for Adobe Support

// Always capture x-request-id from Adobe responses for support escalation
async function debugAdobeCall(url: string, options: RequestInit) {
  const response = await fetch(url, options);

  const debugInfo = {
    url,
    status: response.status,
    requestId: response.headers.get('x-request-id'),
    retryAfter: response.headers.get('Retry-After'),
    contentType: response.headers.get('content-type'),
    date: response.headers.get('date'),
  };

  if (!response.ok) {
    const body = await response.text();
    console.error('Adobe API Error:', { ...debugInfo, body: body.slice(0, 500) });
    // Include x-request-id in support ticket for Adobe to trace the request
  }

  return { response, debugInfo };
}

Support Escalation Template

Adobe Support Ticket

Severity: P[1-4]
x-request-id: [from response header]
Timestamp: [ISO 8601]
Client ID: [first 8 chars only]
API: [Firefly / PDF Services / Photoshop]
Endpoint: [full URL]
HTTP Status: [status code]

Issue Summary: [1-2 sentences]

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

Evidence:
- Layer test results attached
- Verbose curl output attached
- JWT token claims (non-sensitive fields only)

Workarounds Attempted:
1. [What you tried] - [Result]

Output

• IMS token decoded and claims inspected
• HTTP request/response fully traced
• Error codes mapped to recovery actions
• Network layers tested independently
• Support escalation with x-request-id

Error Handling

If a step fails, stop before applying follow-on changes, retain sanitized diagnostic evidence, and use the troubleshooting or escalation guidance already in this skill. Treat authentication and vendor-service failures separately from local configuration errors.

Examples

Start with the smallest applicable command or code example already provided in this guide, using a non-production Adobe environment and credentials. Confirm the documented response or validation result before applying the pattern to production.

Resources

• Adobe Developer Support
• Adobe Status Page
• Firefly API Reference
• PDF Services Error Reference

Next Steps

For load testing, see adobe-load-scale.