Fixing Broken Thumbnails from Teachable CDN Fallback URLs

Release: v1.0.55

Background

When our platform imports a Teachable school, it migrates course assets — including thumbnails — into its own storage. The import pipeline's materialization step (import-materialize.ts) handles this in Step 3 (resolve-thumbnail-url): it first looks for a migrated copy of the thumbnail asset, and if one exists, uses the internal URL.

However, asset migration does not always complete before a course is first accessed. When no migrated asset is found, the fallback path returns originalUrl — the raw Teachable CDN URL — so that learners still see some image rather than nothing.

The Problem

Next.js's <Image /> component (next/image) enforces an allowlist of permitted external hostnames via the remotePatterns configuration in next.config.ts. Only explicitly listed hostnames are allowed to be optimized and served.

Prior to this release, the allowlist contained:

{ protocol: 'https', hostname: '*.teachable.com' }
{ protocol: 'https', hostname: 'process.fs.teachablecdn.com' }

Teachable serves CDN assets from multiple subdomains, including cdn.fs.teachablecdn.com. This hostname is not matched by *.teachable.com (different root domain) and is not the same as the literal string process.fs.teachablecdn.com. As a result, any fallback thumbnail URL on an uncovered subdomain caused next/image to throw an error and render a broken image.

The Fix

The remote patterns allowlist in next.config.ts is updated to use a proper wildcard for the entire teachablecdn.com domain:

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: '*.teachable.com' },
      { protocol: 'https', hostname: '*.teachablecdn.com' }, // ← added
      // Consider also adding:
      // { protocol: 'https', hostname: 's3.amazonaws.com' },
    ],
  },
};

The wildcard *.teachablecdn.com covers cdn.fs.teachablecdn.com, process.fs.teachablecdn.com, and any other subdomain Teachable may use under that domain — future-proofing the configuration against CDN hostname changes.

Why s3.amazonaws.com is Worth Considering

Teachable (and many third-party upload tools integrated with Teachable) occasionally serves assets directly from s3.amazonaws.com or similarly generic cloud storage hosts. If your imported courses include attachments or images uploaded this way, adding s3.amazonaws.com to remotePatterns prevents the same class of error for those assets.

Who Is Affected

Scenario	Affected?
Course thumbnail has been fully migrated to internal storage	✅ No — internal URL is always used
Course thumbnail falls back to a *.teachable.com URL	✅ No — already covered
Course thumbnail falls back to cdn.fs.teachablecdn.com	❌ Yes — broken before this fix
Course thumbnail falls back to other *.teachablecdn.com subdomains	❌ Yes — broken before this fix

No Action Required

This is a configuration-only change in next.config.ts. No import jobs need to be re-run and no data is modified. The fix takes effect automatically on next deployment.

If you are self-hosting the platform, ensure your deployed next.config.ts includes the updated remotePatterns entry before restarting the Next.js server.