> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liv.tv/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes (Unreal)

> Complete error code reference for LCK SDK operations in Unreal Engine.

## What Problem Does This Solve?

When LCK operations fail, you need to know why:

* Was it a permission issue?
* Storage full?
* Already recording?
* Invalid configuration?

Error codes and messages help you handle failures appropriately—show the right error message, retry the operation, or disable features.

## When to Use This

Reference this when:

* Handling recording failures
* Debugging SDK integration issues
* Implementing error recovery logic
* Displaying user-friendly error messages
* Validating configuration before recording

***

## Error Mechanism

<Warning>
  There is no `ELCKError` enum in the SDK. Errors are reported through the `FOnRecordingError` delegate on `ULCKService`, which provides a human-readable `FString ErrorMessage` and an `int32 ErrorCode`.
</Warning>

The following table documents common error codes and their meanings:

| Error                     | Value | What Happened                           | How to Fix                               |
| ------------------------- | ----- | --------------------------------------- | ---------------------------------------- |
| `None`                    | 0     | Operation succeeded                     | -                                        |
| `InvalidTrackingId`       | 1     | Tracking ID missing or invalid format   | Add valid UUID v4 from dashboard         |
| `RecordingAlreadyStarted` | 2     | Start called while already recording    | Check `IsRecording()` first              |
| `NotCurrentlyRecording`   | 3     | Stop called when not recording          | Check recording state                    |
| `EncoderNotAvailable`     | 4     | Platform encoder failed to init         | Check platform requirements, GPU support |
| `InsufficientStorage`     | 5     | Not enough disk space                   | Free up space, reduce quality            |
| `PermissionDenied`        | 6     | Mic/storage permission denied (Android) | Request permissions, guide to settings   |
| `EncodingError`           | 7     | Video/audio encoding failure            | Check logs, reduce quality               |
| `TextureError`            | 8     | Render texture capture failed           | Verify SceneCaptureComponent setup       |
| `AudioError`              | 9     | Audio capture/mixing error              | Check audio source availability          |
| `SaveError`               | 10    | Failed to save recording to disk        | Check permissions, storage, path         |
| `InvalidState`            | 11    | Operation not valid in current state    | Check state before calling               |

***

## Error Handling Patterns

### Basic Synchronous Check

```cpp theme={null}
bool bSuccess = Service->StartRecording();
if (!bSuccess)
{
    UE_LOG(LogLCK, Error, TEXT("Failed to start recording"));
    ShowErrorToUser(TEXT("Recording failed"));
}
```

***

### Async Error Handling (Recommended)

```cpp theme={null}
Recorder->StartRecordingAsync(FOnLCKRecorderBoolResult::CreateLambda([this](bool bSuccess)
{
    if (bSuccess)
    {
        UE_LOG(LogLCK, Log, TEXT("Recording started successfully"));
        ShowRecordingIndicator();
    }
    else
    {
        UE_LOG(LogLCK, Error, TEXT("Failed to start recording"));
        ShowErrorDialog(TEXT("Could not start recording. Please try again."));
    }
}));
```

***

### Validation Before Recording

```cpp theme={null}
void AMyRecorder::AttemptStartRecording()
{
    ULCKDeveloperSettings* Settings = ULCKDeveloperSettings::Get();
    
    // 1. Check tracking ID
    if (!Settings->IsTrackingIdValid())
    {
        UE_LOG(LogLCK, Error, TEXT("Invalid Tracking ID - recording disabled"));
        ShowError(TEXT("Recording not configured. Please contact support."));
        return;
    }
    
    // 2. Validate audio config
    FLCKAudioConfigValidation AudioValidation = Settings->ValidateAudioConfig();
    if (!AudioValidation.bIsValid)
    {
        for (const FString& Warning : AudioValidation.Warnings)
        {
            UE_LOG(LogLCK, Warning, TEXT("Audio warning: %s"), *Warning);
        }
    }
    
    // 3. Check if already recording
    if (Service->IsRecording())
    {
        UE_LOG(LogLCK, Warning, TEXT("Already recording"));
        return;
    }
    
    // 4. Check storage space
    int64 FreeSpace = FPlatformMisc::GetDiskFreeSpace(FPaths::ProjectSavedDir());
    int64 RequiredSpace = 500 * 1024 * 1024; // 500 MB minimum
    if (FreeSpace < RequiredSpace)
    {
        ShowError(TEXT("Not enough storage space to record"));
        return;
    }
    
    // 5. Proceed with recording
    Service->StartRecording();
}
```

***

## Common Error Scenarios

### InvalidTrackingId

**Problem:** The Tracking ID in Project Settings is empty or not in valid UUID v4 format

**Symptoms:**

* Recording immediately fails
* Error log: "Invalid Tracking ID - recording disabled"

**Solution:**

1. Get your Tracking ID from [LIV Developer Dashboard](https://dashboard.liv.tv)
2. Go to **Project Settings → Plugins → LCK SDK**
3. Enter the Tracking ID in format: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`

**Validation code:**

```cpp theme={null}
ULCKDeveloperSettings* Settings = ULCKDeveloperSettings::Get();
if (!Settings->IsTrackingIdValid())
{
    // Show setup instructions to developer
    UE_LOG(LogLCK, Error, TEXT("Tracking ID not configured"));
}
```

***

### RecordingAlreadyStarted

**Problem:** Attempted to start recording while already recording

**Symptoms:**

* Start recording fails
* Confusing UX (button does nothing)

**Solution:** Always check state before starting

```cpp theme={null}
if (!Service->IsRecording())
{
    Service->StartRecording();
}
else
{
    UE_LOG(LogLCK, Warning, TEXT("Recording already in progress"));
}
```

**Better pattern with UI:**

```cpp theme={null}
void ARecordButton::OnPressed()
{
    if (Service->IsRecording())
    {
        // Stop recording
        Service->StopRecording();
        UpdateButtonText(TEXT("Start Recording"));
    }
    else
    {
        // Start recording
        Service->StartRecording();
        UpdateButtonText(TEXT("Stop Recording"));
    }
}
```

***

### EncoderNotAvailable

**Problem:** Platform-specific encoder failed to initialize

**Common reasons:**

* **Windows:** Media Foundation not available (rare, usually on old/stripped Windows)
* **Android:** Hardware encoder not supported (very old devices)
* **Vulkan interop failed** (Android Quest devices)

**Solution:**

1. Check platform requirements
2. Verify GPU supports H.264 encoding
3. Enable verbose logging:

```ini theme={null}
; DefaultEngine.ini
[Core.Log]
LogLCKEncoding=VeryVerbose
```

4. Look for detailed error in `LogLCKEncoding`:
   * Windows: HRESULT error codes
   * Android: MediaCodec configuration errors

**Fallback strategy:**

```cpp theme={null}
Recorder->StartRecordingAsync(FOnLCKRecorderBoolResult::CreateLambda([this](bool bSuccess)
{
    if (!bSuccess)
    {
        // Try lower quality
        Service->StartRecording();
        Service->StartRecording();
    }
}));
```

***

### InsufficientStorage

**Problem:** Not enough free disk space for recording

**How much space is needed:**

* **SD (720p @ 30fps):** \~2 GB per hour
* **HD (1080p @ 60fps):** \~5 GB per hour
* **2K (1440p @ 60fps):** \~9 GB per hour
* **4K (2160p @ 60fps):** \~16 GB per hour

**Solution:**

```cpp theme={null}
// Check before recording
int64 FreeSpace = FPlatformMisc::GetDiskFreeSpace(FPaths::ProjectSavedDir());
int64 MinRequired = 500 * 1024 * 1024; // 500 MB

if (FreeSpace < MinRequired)
{
    ShowError(FString::Printf(
        TEXT("Low storage: Only %d MB free. Need at least 500 MB."),
        FreeSpace / (1024 * 1024)
    ));
    return;
}
```

**Recovery options:**

1. Prompt user to free up space
2. Automatically reduce quality profile
3. Clear old recordings

***

### PermissionDenied

**Problem:** User denied microphone or storage permission on Android

**Android permissions required:**

* `RECORD_AUDIO` — Microphone capture
* `WRITE_EXTERNAL_STORAGE` — Save recordings (API \< 29)

**Solution:**

```cpp theme={null}
// Request permissions at app startup (Android)
#if PLATFORM_ANDROID
void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();
    
    TArray<FString> Permissions;
    Permissions.Add(TEXT("android.permission.RECORD_AUDIO"));
    
    // Request permissions
    UAndroidPermissionFunctionLibrary::RequestPermissions(Permissions);
}
#endif
```

**Handle denial gracefully:**

```cpp theme={null}
if (ErrorCode == 6) // Permission denied
{
    ShowDialog(
        TEXT("Microphone Access Required"),
        TEXT("Please enable microphone access in your device settings to record audio."),
        TEXT("Open Settings"), 
        []() { 
            // Open device settings
            FPlatformProcess::LaunchURL(
                TEXT("app-settings:"), nullptr, nullptr
            );
        }
    );
}
```

***

## Complete Error Handler Example

```cpp theme={null}
UCLASS()
class ARecordingErrorHandler : public AActor
{
    GENERATED_BODY()
    
public:
    UFUNCTION()
    void HandleRecordingError(FString ErrorMessage, int32 ErrorCode)
    {
        UE_LOG(LogLCK, Error, TEXT("Recording error %d: %s"), ErrorCode, *ErrorMessage);

        // Handle by error message content
        if (ErrorMessage.Contains(TEXT("Tracking")))
        {
                ShowError(TEXT("Recording not configured. Contact support."));
                break;
                
            case /* ErrorCode */RecordingAlreadyStarted:
                UE_LOG(LogLCK, Warning, TEXT("Already recording"));
                break;
                
            case /* ErrorCode */EncoderNotAvailable:
                ShowError(TEXT("Your device does not support recording."));
                TryFallbackQuality();
                break;
                
            case /* ErrorCode */InsufficientStorage:
                ShowStorageWarning();
                OfferToReduceQuality();
                break;
                
            case /* ErrorCode */PermissionDenied:
                ShowPermissionPrompt();
                break;
                
            case /* ErrorCode */TextureError:
                UE_LOG(LogLCK, Error, TEXT("Camera capture failed"));
                ResetCameraCapture();
                break;
                
            case /* ErrorCode */AudioError:
                UE_LOG(LogLCK, Error, TEXT("Audio capture failed"));
                DisableAudioRecording();
                break;
                
            case /* ErrorCode */SaveError:
                ShowError(TEXT("Could not save recording. Check storage."));
                break;
                
            default:
                ShowError(TEXT("Recording failed. Please try again."));
                break;
        }
    }
    
private:
    void ShowStorageWarning()
    {
        int64 FreeSpace = FPlatformMisc::GetDiskFreeSpace(FPaths::ProjectSavedDir());
        ShowDialog(FString::Printf(
            TEXT("Low storage: %d MB free. Recording may fail."),
            FreeSpace / (1024 * 1024)
        ));
    }
    
    void OfferToReduceQuality()
    {
        // Show quality reduction option
    }
    
    void TryFallbackQuality()
    {
        Service->StartRecording();
        Service->StartRecording();
    }
};
```

***

## Error Logging

LCK uses Unreal's logging system with these categories:

| Category         | What It Logs                                |
| ---------------- | ------------------------------------------- |
| `LogLCK`         | General SDK operations, state changes       |
| `LogLCKEncoding` | Video/audio encoding, frame capture, muxing |
| `LogLCKAudio`    | Audio capture, mixing, source registration  |
| `LogLCKUI`       | UI interactions, button presses             |
| `LogLCKTablet`   | Tablet lifecycle, camera modes              |

**Enable verbose logging:**

```ini theme={null}
; DefaultEngine.ini
[Core.Log]
LogLCK=VeryVerbose
LogLCKEncoding=VeryVerbose
LogLCKAudio=VeryVerbose
```

**What you'll see:**

```
LogLCK: Recording started
LogLCKEncoding: Encoder initialized: 1920x1080 @ 60fps, 12Mbps
LogLCKAudio: Audio source registered: UnrealAudio
LogLCKEncoding: Frame 0 encoded (8.2ms)
LogLCK: Recording stopped
LogLCKEncoding: Finalizing video file...
LogLCK: Recording saved: /Game/Movies/recording_001.mp4
```

***

## Key Takeaways

<Check>**Always check IsOk/bSuccess** — Never assume operations succeed</Check>
<Check>**Validate before recording** — Check tracking ID, storage, state</Check>
<Check>**Handle common cases** — Storage, permissions, state conflicts</Check>
<Check>**User-friendly messages** — Don't show raw error codes to players</Check>
<Check>**Enable logging for debugging** — VeryVerbose shows detailed encoder info</Check>

***

## Related

* [Enums Reference](/api-reference/unreal/enums) — All enum values including error codes
* [Delegates Reference](/api-reference/unreal/delegates) — Error event delegates
* [Architecture](/api-reference/unreal/architecture) — How errors flow through the system
* [Best Practices](/api-reference/unreal/best-practices) — Error handling patterns