Error codes

When something goes wrong, TCast shows a banner above the status bar with a code like MED-02, what happened, and what to do about it. Red means something failed; yellow is a warning about something worth knowing that hasn't stopped the show. 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 card just above the status bar — red for a failure, yellow for a warning. 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.

MED-06 · Slides won't import

TCast couldn't turn a PDF into slide images. The usual causes are a password-protected deck, a PDF that was only partly downloaded, or a file that was renamed to .pdf but isn't one.

What to do

1. Open the file in Preview. If Preview asks for a password or can't open it either, the file is the problem, not TCast.
2. Re-export it. From Google Slides that's File ▸ Download ▸ PDF Document; from Keynote or PowerPoint, Export to ▸ PDF.
3. If you imported from a link, check the deck is shared with Anyone with the link and try File ▸ Import Slides from Link… again.

MED-07 · Image sequence won't import

TCast couldn't encode a folder of numbered frames into a clip. Usually one unreadable frame, or a folder where the frames aren't all the same size.

What to do

1. Open the folder in Finder and check every frame opens in Preview. One damaged frame stops the whole sequence.
2. Check the frames are all the same pixel size. TCast takes its size from the first frame and scales the rest to match, so an odd one out will look wrong even when it imports.
3. Check free disk space — the encoded clip is written before it's added.

If the folder didn't produce a clip and gave you no code at all, TCast didn't see it as a sequence. It looks for two or more images whose names end in a frame number — shot_0001.png, or just 0001.png.

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.

DSP-02 · Display output stopped

An output was open on a display that disappeared — unplugged, switched to another input, put to sleep, or lost when the Mac woke up somewhere different. TCast closed that output and named the display in the banner.

This is deliberate. A full-screen output window whose display is gone gets moved by macOS onto whatever screen is left, where it covers everything you need, including the menu bar, and has no title bar to close.

What to do

1. Reconnect the display and give macOS a moment to pick it up.
2. Switch the output back on from the sidebar's Display Output group.

TCast won't reopen it for you. A loose cable that comes and goes would otherwise re-light a jumbotron in the middle of a 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.

OUT-03 · OBS browser source can't play this clip

A yellow banner, not a red one — nothing has broken. The clip is on air, and every output except one is playing it normally.

OBS browser sources are Chromium under the hood, and Chromium only decodes the delivery codecs: H.264, HEVC, VP9 and AV1. Hand it a clip in a production codec — ProRes, DNxHD, Animation/RLE, Motion JPEG — and it shows nothing at all. TCast decodes those through macOS, so your display outputs, NDI and Syphon are unaffected.

TCast only raises this when a browser source is actually connected.

What to do

Either point OBS at TCast's Syphon or NDI source instead of the browser source — both take the clip as-is — or re-export the clip as H.264 if you want to keep using the browser source.

See Use TCast as an OBS browser source.

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.