gabrielmoreira 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
curlwith 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
Next Steps
For load testing, see adobe-load-scale.