jackwener/OpenCLI · error · CommandExecutionError

YouTube video metadata is missing playabilityStatus

Error message

YouTube video metadata is missing playabilityStatus

What it means

CommandExecutionError thrown during schema validation of the extracted video payload: payload.playabilityStatus is not a string. The library treats the video metadata shape as a contract; a missing or wrongly-typed playabilityStatus means the page script produced a structurally invalid payload, so it refuses to continue rather than return unreliable data.

Source

Thrown at clis/youtube/video.js:24

import { CommandExecutionError } from '@jackwener/opencli/errors';

function unwrapBrowserResult(value) {
    if (value && typeof value === 'object' && 'session' in value && 'data' in value) {
        return value.data;
    }
    return value;
}

function requireVideoPayload(value) {
    const payload = unwrapBrowserResult(value);
    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
        throw new CommandExecutionError('Failed to extract video metadata from page');
    }
    if (payload.error) {
        throw new CommandExecutionError(String(payload.error));
    }
    if (typeof payload.playabilityStatus !== 'string') {
        throw new CommandExecutionError('YouTube video metadata is missing playabilityStatus');
    }
    if (typeof payload.playabilityReason !== 'string') {
        throw new CommandExecutionError('YouTube video metadata is missing playabilityReason');
    }
    if (typeof payload.membersOnly !== 'boolean') {
        throw new CommandExecutionError('YouTube video metadata is missing membersOnly');
    }
    return payload;
}

cli({
    site: 'youtube',
    name: 'video',
    access: 'read',
    description: 'Get YouTube video metadata (title, views, description, etc.)',
    domain: 'www.youtube.com',
    strategy: Strategy.COOKIE,
    args: [

View on GitHub (pinned to 49907e53dc)

Solutions

Update the library/tooling to match the current YouTube player response schema.
Ensure the video watch page fully loaded (wait for player data/ytcfg) before extraction.
Log the raw payload to inspect what fields were actually extracted and compare with the expected schema.
Retry the extraction; if it consistently fails, the page structure likely changed and needs a code fix.

Defensive patterns

Strategy: validation

Validate before calling

const payload = unwrapBrowserResult(raw);
if (!payload || typeof payload.playabilityStatus !== 'string') {
  throw new Error('Invalid video payload: playabilityStatus must be a string');
}

Type guard

function hasPlayabilityStatus(p) {
  return p != null && typeof p === 'object' && typeof p.playabilityStatus === 'string';
}

Try / catch

try {
  const info = await video(url);
} catch (e) {
  if (e.name === 'CommandExecutionError' && /playabilityStatus/.test(e.message)) {
    console.error('YouTube payload schema changed');
  }
  throw e;
}

Prevention

Wait for the player response/ytcfg to be populated before extracting metadata.
Log raw payloads when validation fails to spot YouTube schema drift early.
Pin/update the library when YouTube renames or relocates playabilityStatus.
Retry extraction once before concluding the page structure changed.

When it happens

Trigger: The in-page extraction returned an object without a string playabilityStatus — e.g. YouTube changed the player response structure, or the script short-circuited on an unexpected page state.

Common situations: YouTube front-end updates renaming/moving playabilityStatus; extraction running on a non-watch page or consent interstitial; scripts grabbing ytcfg/player data before the player response is populated.

Related errors

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