jackwener/OpenCLI · error · CommandExecutionError

Instagram private publish configure_sidecar failed

Error message

Instagram private publish configure_sidecar failed

What it means

Inside the retry loop, if Instagram's configure_sidecar JSON body has status:'fail', the library throws this error with the server's message (or first 500 chars of the body) as detail. This is Instagram explicitly reporting the sidecar configure failed for a content/policy/API reason, as opposed to an HTTP-level failure.

Source

Thrown at clis/instagram/_shared/private-publish.js:870

        }
        catch {
            throw new CommandExecutionError('Instagram private publish configure_sidecar returned invalid JSON');
        }
        if (!response.ok) {
            const detail = text ? ` ${text.slice(0, 500)}` : '';
            throw new CommandExecutionError(`Instagram private publish configure_sidecar failed: ${response.status}${detail}`);
        }
        const message = String(json?.message || '');
        if (response.status === 202
            || /transcode not finished yet/i.test(message)) {
            if (attempt >= INSTAGRAM_PRIVATE_SIDECAR_TRANSCODE_ATTEMPTS - 1) {
                throw new CommandExecutionError('Instagram private publish configure_sidecar timed out waiting for video transcode', text.slice(0, 500));
            }
            await waitMs(INSTAGRAM_PRIVATE_SIDECAR_TRANSCODE_WAIT_MS);
            continue;
        }
        if (String(json?.status || '').toLowerCase() === 'fail') {
            throw new CommandExecutionError('Instagram private publish configure_sidecar failed', message || text.slice(0, 500));
        }
        return { code: json?.media?.code };
    }
    throw new CommandExecutionError('Instagram private publish configure_sidecar failed');
}
export async function publishMediaViaPrivateApi(input) {
    const now = input.now ?? (() => Date.now());
    const clientSidecarId = String(now());
    const uploadIds = input.mediaItems.length > 1
        ? input.mediaItems.map((_, index) => String(now() + index + 1))
        : [String(now())];
    const fetcher = input.fetcher ?? ((url, init) => instagramPrivateApiFetch(input.page, url, init));
    const prepareMediaAsset = input.prepareMediaAsset ?? prepareInstagramMediaAsset;
    const assets = await Promise.all(input.mediaItems.map((item) => prepareMediaAsset(item)));
    try {
        for (let index = 0; index < assets.length; index += 1) {
            const asset = assets[index];
            const uploadId = uploadIds[index];

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Read the detail string attached to the error — it contains Instagram's own failure message.
  2. Verify all upload ids in the sidecar payload correspond to successfully completed uploads.
  3. Test with a single image publish to rule out account-level action blocks.
  4. Reduce media count / change caption to rule out content policy triggers.
  5. Wait before retrying — Instagram action blocks are often temporary.
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check content basics before publish
if (caption.length > 2200) throw new Error('Caption too long — configure_sidecar would fail');

Type guard

function isSidecarSuccess(json) {
  return typeof json === 'object' && json !== null && json.status !== 'fail' && typeof json.media?.code === 'string';
}

Try / catch

try {
  await publishMediaViaPrivateApi({ mediaItems, apiContext });
} catch (e) {
  if (/configure_sidecar failed$/.test(e.message)) {
    console.error('Instagram said:', e.detail ?? e.message); // server's failure reason
  }
  throw e;
}

Prevention

When it happens

Trigger: A configure_sidecar response with a 2xx status whose JSON has status === 'fail' (case-insensitive); thrown with json.message or the body excerpt as the CommandExecutionError detail.

Common situations: Media policy violation flagged at configure time; an upload id invalid or expired at configure time; caption or media combination rejected; account restrictions (action block, shadowban).

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/f294a8a09322192d. Report an issue: GitHub.