{"record":{"id":"ea9c27e58fb043ed","repo":"paperclipai/paperclip","slug":"assets-must-be-a-real-directory","errorCode":null,"errorMessage":"Assets must be a real directory","messagePattern":"Assets must be a real directory","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/publish-announcements.ts","lineNumber":53,"sourceCode":"      sourceDirectory = arg;\n    }\n  }\n  return { sourceDirectory: sourceDirectory ?? (staging ? \"announcements/examples/staging\" : \"announcements\"), staging, publish: mode === \"publish\" };\n}\n\nexport async function prepareAnnouncementPublish(sourceDirectory: string, staging?: string, hostPrefix?: string) {\n  const prefix = announcementPublishPrefix(staging, hostPrefix);\n  const source = path.resolve(sourceDirectory);\n  if (!(await lstat(source)).isDirectory()) throw new Error(\"Source must be a real directory\");\n  const manifestPath = path.join(source, \"current.json\");\n  const stat = await lstat(manifestPath);\n  if (!stat.isFile() || stat.size > ANNOUNCEMENT_MANIFEST_MAX_BYTES) throw new Error(\"Invalid or oversized current.json\");\n  const manifest = announcementManifestSchema.parse(JSON.parse(await readFile(manifestPath, \"utf8\")));\n  const files: Array<{ file: string; key: string; contentType: string; cacheControl: string }> = [];\n  for (const kind of [\"image\", \"animation\"] as const) {\n    const asset = manifest.announcement?.[kind];\n    if (!asset) continue;\n    if (!(await lstat(path.join(source, \"assets\"))).isDirectory()) throw new Error(\"Assets must be a real directory\");\n    const assetPath = asset.path;\n    const file = path.join(source, assetPath);\n    const assetStat = await lstat(file);\n    const maximum = kind === \"animation\" ? ANNOUNCEMENT_ANIMATION_MAX_BYTES : ANNOUNCEMENT_IMAGE_MAX_BYTES;\n    if (!assetStat.isFile() || assetStat.size > maximum) throw new Error(`Invalid or oversized ${kind}`);\n    const bytes = await readFile(file);\n    const digest = createHash(\"sha256\").update(bytes).digest(\"hex\");\n    if (!assetPath.startsWith(`assets/${digest}.`)) throw new Error(\"Asset filename must match its SHA-256 digest\");\n    if (kind === \"animation\") validateAnnouncementAnimation(bytes);\n    files.push({ file, key: `${prefix}/${assetPath}`, contentType: kind === \"animation\" ? \"text/html\" : assetPath.endsWith(\".png\") ? \"image/png\" : assetPath.endsWith(\".jpg\") ? \"image/jpeg\" : \"image/webp\", cacheControl: \"public,max-age=31536000,immutable\" });\n  }\n  files.push({ file: manifestPath, key: `${prefix}/current.json`, contentType: \"application/json\", cacheControl: \"public,max-age=300\" });\n  return { manifest, files };\n}\n\nexport function announcementUploadArgs(bucket: string, file: Awaited<ReturnType<typeof prepareAnnouncementPublish>>[\"files\"][number]) {\n  return [\"s3api\", \"put-object\", \"--bucket\", bucket, \"--key\", file.key, \"--body\", file.file,\n    \"--content-type\", file.contentType, \"--cache-control\", file.cacheControl];","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/scripts/publish-announcements.ts#L35-L71","documentation":"prepareAnnouncementPublish validates the announcement bundle before uploading it to the page host. When the manifest declares an image or animation asset, it requires the bundle's assets/ entry to be a real directory (checked with lstat, not stat, so symlinks fail). This error means the assets path is missing, is a file, or is a symlink rather than a genuine directory.","triggerScenarios":"The manifest contains announcement.image or announcement.animation, but `<source>/assets` does not exist, is a regular file, or is a symlink to a directory. lstat().isDirectory() returns false in all those cases.","commonSituations":"Exporting an announcement directory without its assets folder; packaging the bundle by copying only current.json; using a symlinked assets directory from a shared cache; running the publish script from the wrong source directory.","solutions":["Create the missing assets/ directory next to current.json and place the manifest's asset file at its declared path","Replace the assets symlink with a real directory containing the asset files","Verify you pointed the script's source directory argument at the correct announcement bundle root","Re-export or re-package the announcement bundle so assets are materialized on disk"],"exampleFix":"// before (assets is a symlink or missing)\nls announcement/  # current.json only\n// after\nmkdir -p announcement/assets\ncp image.png announcement/assets/<sha256>.png","handlingStrategy":"validation","validationCode":"import { lstat } from \"node:fs/promises\";\nconst s = await lstat(path.join(source, \"assets\"));\nif (!s.isDirectory()) throw new Error(\"assets must be a real directory, not a symlink/file\");","typeGuard":"const isRealDir = async (p: string) => { try { return (await lstat(p)).isDirectory(); } catch { return false; } };","tryCatchPattern":"try { await prepareAnnouncementPublish(src, staging, prefix); } catch (e) { if (e.message === \"Assets must be a real directory\") { /* repair bundle: mkdir assets, remove symlink */ } }","preventionTips":["Always package announcement bundles with a real assets/ directory, not symlinks","Run a pre-publish validation of the bundle layout (manifest + assets present)","Verify the source directory argument points at the bundle root before running","Never copy only current.json when moving announcements between environments"],"tags":["filesystem","announcements","validation"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-22T06:17:15.046Z"}