使用AVPlayerViewController时出现CUICatalog无效资源名(null)错误求助

Hey there! I totally get how confusing this error can be when you’re just starting out—especially since your video works fine with AVPlayer + PlayerLayer! Let’s break down why this is happening with AVPlayerViewController and how to fix it step by step.

First, let’s understand the root issue #

Since your video plays without errors using AVPlayer directly, the problem isn’t with the video file itself. That (null) asset error means AVPlayerViewController is trying to load some resource that doesn’t exist (or is accidentally set to nil somewhere in your setup). The built-in UI controls of AVPlayerViewController rely on system assets, so even a tiny misconfiguration can trigger this.

Here are the most common fixes to try: #

1. Double-check your video URL and player assignment

It’s easy to accidentally pass a nil URL to AVPlayer, or forget to properly bind the player to AVPlayerViewController. Let’s use this correct code pattern as a reference:

import AVKit
import UIKit

class YourViewController: UIViewController {
    // 假设你通过按钮点击触发播放
    @IBAction func playVideoTapped(_ sender: UIButton) {
        // 1. 确保能正确从Bundle获取视频URL（文件名和扩展名要完全匹配，大小写敏感！）
        guard let videoURL = Bundle.main.url(forResource: "your-video-filename", withExtension: "mp4") else {
            print("Error: 找不到视频文件！请检查文件名和扩展名")
            return
        }
        
        // 2. 创建AVPlayer实例
        let player = AVPlayer(url: videoURL)
        
        // 3. 初始化AVPlayerViewController并绑定player（这一步绝对不能漏！）
        let playerVC = AVPlayerViewController()
        playerVC.player = player
        
        // 4. 展示播放器并开始播放
        present(playerVC, animated: true) {
            player.play()
        }
    }
}

2. Verify your video file’s Target Membership

Even if you added the video to your project, it might not be included in your app’s final build. Here’s how to check:

• In Xcode, select your video file in the Project Navigator.
• Look at the File Inspector (right-hand sidebar).
• Under Target Membership, make sure the checkbox next to your app’s target is checked. If not, tick it and rebuild your project.

3. Clean your project’s build cache

Xcode sometimes holds onto old cached resources that cause weird, unexplained issues. Try this quick fix:

• Go to Product > Clean Build Folder (hold down the Option key if you don’t see this option immediately).
• Then re-run your project.

4. Check for accidental Storyboard misconfigurations

If you’re using a Storyboard to add AVPlayerViewController, double-check that you haven’t set any asset-related properties to empty values:

• Make sure you haven’t linked a broken image or resource to the player’s overlay controls.
• If you’re using a custom player UI in Storyboard, ensure all referenced assets exist in your project.

Why does this work with AVPlayer + PlayerLayer but not AVPlayerViewController? #

AVPlayer only handles core video playback, but AVPlayerViewController comes with pre-built UI controls (play/pause, volume, fullscreen) that rely on system assets. If any part of its setup is incomplete (like a nil player or broken video URL), it throws that CUICatalog error.

Give these steps a try—chances are one of them will resolve the issue!

内容的提问来源于stack exchange，提问作者Jonathan Carpenter