Apply advanced debugging techniques for Adobe API issues: IMS token introspection, Firefly job failure analysis, PDF Services error codes, and network-layer diagnostics for Adobe endpoints. Trigger with phrases like "adobe hard bug", "adobe mystery error", "adobe impossible to debug", "difficult adobe issue", "adobe deep debug".
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.
curl with verbose mode for HTTP debuggingtcpdump, openssl s_client)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 | python3 -m json.tool
# 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
# 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
// When async Firefly jobs fail, the status endpoint returns error details
async function diagnoseFireflyJob(jobId: string, statusUrl: string) {
const token = await getAccessToken();
const response = await fetch(statusUrl, {
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()));
}
// 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}`;
}
#!/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
// 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 };
}
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]
For load testing, see adobe-load-scale.