Troubleshooting

Before anything else, two fixes that solve more problems than you'd expect:

Restart the game. Campaign files, VPKs and Workshop items are only picked up at startup.
Remove your loose test files. Files in bms/maps/, bms/materials/ and so on can hide (or clash with) what's in your VPK or Workshop item.

Launching with -dev -console makes the game print warnings about missing files, which often point straight at the problem.

Your map loads with map yourmapname, but it isn't listed on the Campaigns tab of the main menu's Add-ons section.

There's no campaign file. The menu lists campaigns, not maps. Every Workshop item that should appear there needs a campaigns/<name>.json, even a single map. See Creating a campaign.
The file is called blackmesa.json. That name is reserved for the official campaign, so it's never listed on the Campaigns tab. It replaces the New Game list instead. Rename it to something unique.
The JSON is invalid. One stray comma hides the whole campaign, and the game doesn't say why. Paste it into a JSON validator. Look especially for a trailing comma after the last chapter, // comments, curly quotes, or the extra outer braces from the old wiki template. See Check the JSON is valid.
It's in the wrong folder. It must be at campaigns/ in the root of your VPK, not inside maps/ or ui/.
The game hasn't restarted since you added the file or subscribed.

Campaign card or chapter has no picture

The imageSource path must start with image://game/ followed by the file's path from the root of your mod: image://game/ui/mymod/chapter1.png. Don't include bms/, materials/ (unless that's really where the file is) or a drive letter.
Check the image is really in your VPK at that path, spelled the same way (use lowercase throughout).
Use PNG or JPG.

Choosing a chapter loads the wrong map, or nothing

levelName must be the map's file name without .bsp or maps/: "ap_01_lobby", not "maps/ap_01_lobby.bsp". Check the spelling against the actual file in your VPK.

Titles show as hash tokens

Your campaign or chapters appear as #MYMOD_Chapter1_Title instead of a name. Those are localization tokens, and a Workshop item can't add the translation files they need. Use plain text titles in your campaign file. (In a standalone mod, save your resource/<mod>_english.txt as UTF-16 LE.)

The official campaign changed or broke

After subscribing to an item, New Game shows the wrong chapters, artwork or text, or official chapters won't unlock. An item is shipping a file that replaces a base game file:

campaigns/blackmesa.json replaces the New Game list.
scripts/chapter_manifest.txt in bms/custom/ changes which official chapters unlock. (A Workshop item's copy is ignored, so check your test VPKs.)
ui/campaign/images/chapter*.png replaces official chapter art.
Files in resource/ replace game text.

To find which item it is, unsubscribe from items one at a time (restarting each time). If it's yours, remove the file from your VPK; your item doesn't need it. See Same path, same file.

Game text, sounds or weapons are out of date

After subscribing to an item, a chapter has the wrong name (for example Xen shows as CREDITS), item names are spelled differently, or weapons, sounds or the HUD behave like an older version of the game. The item contains a copy of one of the game's own VPKs, or files taken out of one, and its old copies replace the current files.

Find the item the same way: unsubscribe one at a time, restarting each time. If it's yours, rebuild your VPK with only the files you made. See Don't repack the game's own files.

Custom multiplayer map isn't in the Host list

The Host screen adds subscribed Workshop maps after the official ones. If yours is missing:

It isn't from the Workshop. Local test copies in bms/maps/ or bms/custom/ aren't listed. Start them from the console: maxplayers 12, then map dm_yourmap.
The name doesn't start with dm_ or tdm_.
The item isn't a VPK. Workshop items uploaded as loose folders aren't mounted, so the map can't be played at all. The Subscribed tab of the Add-ons menu shows these as Not Mounted. Repack it as a VPK and update the item.

See Multiplayer maps.

Loading screens

Loading screen has no image

The loading screen shows the main menu's background, the last level's image, or black.

Singleplayer maps use the image of the chapter they belong to:

The chapter has no imageSource, or its path is wrong (see Campaign card or chapter has no picture).
The map isn't matched to any chapter. Only the first map of each chapter is listed in the campaign file. Later maps are matched by name: they must share their first four letters with a chapter's first map and sort after it alphabetically. Maps named lobby, offices, vault don't match each other; ap_01_lobby, ap_02_offices, ap_03_vault do. See How maps are matched to chapters.

Multiplayer maps need maps/<mapname>.txt and generated images:

Check that the .txt file is named exactly like the .bsp and its first line is the map name.
Check that each path under "Images" is relative to materials/vgui/, e.g. multiplayer/map_backgrounds/dm_mymap_0, with no .vmt and no _widescreen suffix.
Check that the .vtf and .vmt files are actually in your VPK under materials/vgui/multiplayer/map_backgrounds/.

See Loading screens.

Purple-and-black checkerboard instead of the loading image

The game couldn't load the image. If you added the files while the game was running, restart it. Otherwise one of the .vtf / .vmt files is missing, or its name doesn't match the .txt file. Regenerate the images if a capture failed.

Loading image is stretched or squashed

The image for that screen shape is missing or was copied from another shape. Generate the images at all three aspect ratios (4:3, 16:9 and 16:10), changing resolution and restarting between runs. See Repeat for each screen shape.

The player spawns somewhere other than the loading image

The numbers in "Images" don't match the info_observer_menu IDs. IDs must start at 0, count up with no gaps or duplicates, and image "1" must have been taken from camera 1.

Loading images are blurry or missing objects

Motion blur was on, or something was touched during capture. Run mat_motion_blur_enabled 0, then bm_generate_menu_images again, and don't move the mouse or type until it prints Done!

In the game

Missing textures or ERROR models

Purple-and-black checkerboards, or red ERROR signs where models should be, mean files are missing from your VPK.

On your PC everything looked fine because the files are also loose in bms/. Remove them and test the VPK on its own.
Every custom texture needs both its .vtf and its .vmt. Every model needs its .mdl, .vvd and .vtx files (and .phy if it has physics).
Check paths and spelling: the .vmt's $basetexture points at a .vtf, and the map points at the .vmt.

NPCs stand still or walk into walls

The nodegraph is missing or out of date. Delete maps/graphs/<mapname>.ain, load the map to rebuild it, and ship the new file. The map also needs info_node entities where NPCs should be able to walk.

Shiny surfaces look black, wrong or too bright

Cubemaps weren't built, or were lost when you recompiled. Build them again after your final compile. See Cubemaps.

My changes don't show up

Did you rebuild the VPK after changing files, and copy it into the upload folder?
Is an older copy still around, in bms/custom/, loose in bms/, or as an old Workshop subscription, taking priority?
For Workshop updates, Steam may not have downloaded the new version yet. Restart Steam to force a check.

Hammer and compiling

Black Mesa entities are missing in Hammer

Add bin/bms.fgd under Tools → Options → Game Configurations → Game Data files. See Setting up the tools.

VPROJECT error, or Hammer loads another game's content

Set the VProject environment variable to your Black Mesa/bms folder. See If Hammer complains about VPROJECT.

Lighting looks flat compared to the official maps

Use the final compile settings for your map type, and consider new lights for key light sources.

Publishing

The publishing tool won't upload

Workshop agreement error: accept the Steam Workshop contribution agreement, then try again.
Content folder error: choose a folder that exists and contains your VPK.
Title or description error: neither can be blank.
Failed to query your published content: make sure Steam is running and signed in, then restart Steam and the tool.

Nobody else can see my item

Check its visibility on its Steam page, and make sure you've accepted the contribution agreement. Items stay hidden until you do.

Still stuck?

Ask in the Crowbar Collective Discord. Include what you expected, what happened instead, and any console errors. Screenshots of your campaign file and folder layout help a lot.

Menu and campaigns

Campaign is missing from the menu