jlcodes99/cockpit-tools · warning

[ExternalImport][App] payload 归一化失败，已忽略

Error message

[ExternalImport][App] payload 归一化失败，已忽略

What it means

handleExternalProviderImportRawPayload logs the raw external import payload and passes it through normalizeExternalProviderImportPayload. If normalization returns null/undefined the payload does not conform to the expected external import schema (missing or wrongly-typed fields such as providerId), so the app logs this warning and drops the payload without importing.

Source

Thrown at src/App.tsx:973

            variant: 'secondary',
          },
        ],
      });
      console.warn('[ExternalImport][App] 当前版本不支持外部导入方式，已终止导入', {
        currentVersion: currentVersion || null,
        requiredVersion,
        providerId: payload.providerId,
      });
      return false;
    },
    [showModal, t],
  );

  const handleExternalProviderImportRawPayload = useCallback(async (rawPayload: unknown) => {
    console.info('[ExternalImport][App] 收到原始 payload:', rawPayload);
    const normalized = normalizeExternalProviderImportPayload(rawPayload);
    if (!normalized) {
      console.warn('[ExternalImport][App] payload 归一化失败，已忽略');
      return;
    }
    if (!(await ensureExternalImportVersionCompatible(normalized))) {
      return;
    }
    const now = Date.now();
    for (const [key, handledAt] of externalImportHandledAtRef.current) {
      if (now - handledAt > EXTERNAL_IMPORT_DEDUPE_WINDOW_MS) {
        externalImportHandledAtRef.current.delete(key);
      }
    }
    const dedupeKey = buildExternalImportDedupeKey(normalized);
    if (externalImportHandledAtRef.current.has(dedupeKey)) {
      console.info('[ExternalImport][App] 重复外部导入 payload 已忽略');
      return;
    }
    externalImportHandledAtRef.current.set(dedupeKey, now);
    console.info('[ExternalImport][App] payload 归一化成功:', {

View on GitHub (pinned to 1ed8b77992)

Solutions

1. Check the logged '[ExternalImport][App] 收到原始 payload:' line immediately above to see which field failed the schema.
2. Regenerate the import payload from a valid export rather than editing it by hand.
3. Validate the payload against the external import schema before sharing (all required fields present, correct types).
4. If it comes from another tool, confirm the payload matches this app's external import format/version.

Example fix

// before
console.info('[ExternalImport][App] 收到原始 payload:', rawPayload);
const normalized = normalizeExternalProviderImportPayload(rawPayload);
if (!normalized) {
  console.warn('[ExternalImport][App] payload 归一化失败，已忽略');
  return;
}
// after
const parsed = ExternalProviderImportPayloadSchema.safeParse(rawPayload);
if (!parsed.success) {
  console.warn('[ExternalImport][App] payload 归一化失败:', parsed.error.issues);
  return;
}
const normalized = normalizeExternalProviderImportPayload(parsed.data);

function isValidExternalImportPayload(p: unknown): boolean {
  if (typeof p !== 'object' || p === null) return false;
  const o = p as Record<string, unknown>;
  return typeof o.providerId === 'string' && o.providerId.length > 0 &&
    typeof o.requiredVersion === 'string';
}
if (!isValidExternalImportPayload(rawPayload)) return;

function isExternalImportPayload(v: unknown): v is ExternalProviderImportPayload {
  return (
    typeof v === 'object' && v !== null &&
    typeof (v as any).providerId === 'string' &&
    typeof (v as any).config === 'object'
  );
}

let rawPayload: unknown;
try {
  rawPayload = JSON.parse(payloadSource);
} catch {
  console.warn('[ExternalImport][App] payload JSON 解析失败');
  return;
}
const normalized = normalizeExternalProviderImportPayload(rawPayload);
if (!normalized) {
  console.warn('[ExternalImport][App] payload 归一化失败，已忽略');
  return;
}

When it happens

Trigger: Receiving a raw payload (deep link, clipboard, file drop) whose shape fails validation: missing providerId, wrong types for nested fields, malformed JSON that was partially parsed, or an unknown schema version.

Common situations: Hand-edited or truncated shared import files, exports from incompatible third-party tools, copy/paste losing part of the payload, or URL encoding mangling fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• invalidJsonMessage
• messages.noItems
• messages.providerMismatch
• invalid_bundle_root
• invalid_bundle_schema

AI-assisted analysis of jlcodes99/cockpit-tools@1ed8b77992 (2026-09-05). Data as JSON: /api/errors/c35979619ddbbb64. Report an issue: GitHub.