Error codes

When something goes wrong, TCast shows a red banner above the status bar with a code like MED-02, what happened, and what to do about it. This page is the full list, with a bit more detail than fits on a banner.

Every code is stable. MED-02 means the same thing in every version, so quoting one in an email to support is the fastest way to get a specific answer.

Where the codes appear

The banner, a red card just above the status bar, for whatever just failed. Up to three stack at once, newest on top. Each has its own ✕.

Dismissing a banner clears the card, not the problem. The issue stays in the count and the list below, and if the same thing goes wrong again the banner comes back.

The status bar count, a red ⚠ 2 issues at the right-hand end of the bottom bar, next to the clock. Click it to open the list. It only appears when there's something to see, and it goes down on its own when a problem clears. Relink a missing clip and its issue disappears.

Settings ▸ General ▸ Recent Issues, the last 20, newest first, with the time each happened. Copy All puts the lot on the clipboard.

A ×3 next to a code means TCast hit that same failure three times by itself, for example a looping playlist coming back round to a clip whose file is gone. Clicking a dead clip yourself doesn't add to it. That's one broken file however many times you try it.

Sending a code to support

Two ways, both fine:

• Copy Details on the banner. You get the code, what failed, and your TCast and macOS versions. Paste it into an email to support@tcast.app.
• Settings ▸ General ▸ Feedback. Write what happened and send. The recent codes are attached automatically, so you don't need to copy anything.

Only the codes are sent, never your file paths or your media.

If support asks for the log:

log show --last 1h --predicate 'subsystem == "app.tcast"'

Run that in Terminal after reproducing the problem.

MED — Media and playback

MED-01 · Clip is missing

The file isn't where TCast left it. Something moved, renamed, or deleted it, or the drive it lives on isn't mounted.

What to do

1. If the clip is on an external drive, reconnect it. TCast re-checks at play time, so the clip usually comes straight back.
2. Otherwise right-click the card and choose Relink…, then point TCast at the file's new home.
3. Moved a whole folder? In Settings ▸ Media ▸ Offline Media, click Search for offline media… and pick it. TCast searches that folder and its subfolders for files with the same name, and relinks them automatically at startup from then on.

Offline clips show an orange OFFLINE badge on their card and play nothing if you click them. A playlist running on its own skips them and keeps going, so one missing file never stops a show. Clicking one by hand does nothing but beep, so you never get a clip you didn't ask for.

MED-02 · Clip won't play

macOS can't decode this format. The file itself is intact; the problem is the codec inside it, which AVFoundation won't touch. ProRes RAW, some DNxHD variants, exotic MKV streams, and video files with a misleading extension all land here.

What to do

Re-export as H.264 or HEVC in a .mov or .mp4. Both are hardware decoded on Apple silicon, so they're also the cheapest thing you can play.

MED-03 · Clip took too long to load

TCast gives a clip 8 seconds to open. Past that it gives up rather than hold the program.

What to do

• Spinning drive or network volume asleep? Play a clip from it once to wake it before the show.
• On a NAS or SMB share, copy the media to the internal disk. Network storage is the usual cause.
• If it happens on a local SSD, the file is probably damaged. Re-export it.

MED-04 · Image won't open

The file couldn't be read as an image, even after a fallback attempt. Usually a corrupt file, an unusual format, or something that isn't really an image.

What to do

Re-export as PNG or JPEG.

MED-05 · Couldn't add to the media library

An upload or import arrived but couldn't be written into TCast's media folder.

What to do

1. Check free disk space on the startup volume.
2. Check that ~/Library/Application Support/TCast is writable. Settings ▸ General ▸ Data ▸ Reveal in Finder takes you there.
3. Try again. Whoever was uploading sees the same code on their upload page.

REN — Video engine

REN-01 · Video engine couldn't start

TCast couldn't build its renderer. Your media and your Mac's graphics aren't the cause; this means the app bundle is damaged or incomplete.

What to do

Reinstall TCast. If it happens again on a clean install, send REN-01 to support with your Mac model and macOS version. That one really is a bug.

DSP — Display outputs

DSP-01 · Couldn't open display output

TCast tried to put the program full-screen on a display that isn't there any more, or couldn't build a renderer for it.

What to do

1. Check the cable, adapter, and that the display is on.
2. Confirm the display appears in System Settings ▸ Displays.
3. Open the output again from the sidebar's Display Output group.

If a display was unplugged mid-show, plug it back in and re-open the output. TCast leaves it closed rather than reopening it for you, in case that's not what you wanted mid-programme.

OUT — NDI and Syphon

OUT-01 · NDI output couldn't start

The NDI runtime isn't installed, is a version TCast can't use, or another app has the sender name.

What to do

1. Install NDI Tools from ndi.video. The runtime ships with it, and TCast can't send NDI without it.
2. Restart TCast after installing.
3. Still failing? Quit other NDI senders and try again.

See Send your program over NDI.

OUT-02 · Syphon output couldn't start

The Syphon server couldn't be created. Usually a stale server from a previous run is still holding the name.

What to do

Quit and reopen TCast. If a receiving app such as OBS, Resolume, or MadMapper was mid-crash, quit that too before restarting.

See Send your program over Syphon.

NET — Network outputs and control

NET-01 · Browser output couldn't start

TCast couldn't open the port that serves the OBS Browser Source and the upload page. Almost always a second copy of TCast already running.

What to do

1. Check for another TCast in the Dock or in Activity Monitor and quit it.
2. Restart TCast.

Without this, the OBS Browser Source and browser uploads won't work. Display outputs, NDI, and Syphon are unaffected, since they don't go through the network.

See Bring your program into OBS as a Browser Source.

NET-02 · Remote control couldn't start

TCast couldn't open its remote-control port, so Companion and the iPhone remote can't connect over Wi-Fi.

What to do

1. Change the port in Settings ▸ Remote Control ▸ Wi-Fi and try again. Anything above 1024 that nothing else is using.
2. Check nothing else on this Mac has claimed it.

The Bluetooth remote path doesn't use a port and keeps working either way.

See Control TCast from a Stream Deck.

PRJ — Projects and saving

PRJ-01 · Couldn't open project

TCast couldn't read a .tcast file. It's damaged, truncated, or was saved by a newer version of TCast than this one.

What to do

1. Update TCast. A project from a newer version won't open in an older one.
2. Check the file isn't on a disconnected drive, and that it isn't 0 bytes.
3. If it's genuinely damaged, open a recent copy from a backup. TCast writes projects atomically, so a crash mid-save leaves the previous version intact rather than a half-written file.

PRJ-02 · Couldn't save to disk

A write failed. This covers projects, settings, and the media catalog, all of which TCast saves automatically as you work.

Take this one seriously: until it clears, your changes aren't on disk.

What to do

1. Check the disk isn't full.
2. Check the folder the project lives in still exists and is writable. This usually means an external drive was ejected with the project on it.
3. Reconnect the drive. TCast saves constantly, so the next successful write clears the issue on its own and the count drops.

If you can't reconnect it, use File ▸ Save As… to put the project somewhere local before quitting.

LIC — Licensing

LIC-01 · Couldn't store your license

TCast couldn't write your license to the login keychain, so it would be gone on the next launch and the Mac would drop to the free tier.

What to do

1. Unlock your login keychain. This happens most often on a Mac that auto-logs-in without a password, or when Keychain Access has it locked.
2. Enter your key again in Settings ▸ License.

Your key survives this. You can always re-enter it, and re-activating on the same Mac doesn't use up another seat. See Licensing.

Codes not on this page

If you see a code that isn't listed here, it's from a newer version of TCast than this page covers. Send it to support@tcast.app with what you were doing at the time.