tui-cs/Terminal.Gui · critical · ArgumentException

Driver '{driverName}' is not registered in DriverRegistry.

Error message

Driver '{driverName}' is not registered in DriverRegistry.

What it means

Thrown by ApplicationImpl.CreateDriver when a driverName is passed (or set via ForceDriver) that does not exist in DriverRegistry. The registry only knows the built-in names: "Windows", "DotNet", and "ANSI". Any other string fails DriverRegistry.TryGetDriver and triggers this ArgumentException before any driver is constructed.

Source

Thrown at Terminal.Gui/App/ApplicationImpl.Driver.cs:57

            }
            else if (_componentFactory is IComponentFactory<ConsoleKeyInfo> netFactory)
            {
                Coordinator = CreateSubcomponents (() => netFactory);
            }
            else if (_componentFactory is IComponentFactory<char> unixFactory)
            {
                Coordinator = CreateSubcomponents (() => unixFactory);
            }
            else
            {
                throw new InvalidOperationException ($"Unknown component factory type: {_componentFactory.GetType ().Name}");
            }
        }
        else
        {
            if (!string.IsNullOrEmpty (driverName) && !DriverRegistry.TryGetDriver (driverName, out _))
            {
                throw new ArgumentException ($"Driver '{driverName}' is not registered in DriverRegistry.");
            }

            // Determine which driver to use
            if (!string.IsNullOrEmpty (driverName) && DriverRegistry.TryGetDriver (driverName, out DriverRegistry.DriverDescriptor? descriptor))
            {
                // Use explicitly specified driver name
                _driverName = descriptor!.Name;
                Trace.Lifecycle (MainThreadId?.ToString (), "Init", $"Using driver specified by parameter: {descriptor.Name} ({descriptor.DisplayName})");
            }
            else if (!string.IsNullOrEmpty (ForceDriver) && DriverRegistry.TryGetDriver (ForceDriver, out descriptor))
            {
                // Use ForceDriver configuration property
                _driverName = descriptor!.Name;

                Trace.Lifecycle (MainThreadId?.ToString (),
                                 "Init",
                                 $"Using driver from ForceDriver configuration: {descriptor.Name} ({descriptor.DisplayName})");
            }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Use one of the valid built-in driver names: "Windows", "DotNet", or "ANSI".
2. Pass null/empty driverName to let DriverRegistry auto-select the platform default driver (GetDefaultDriver).
3. If you need a custom driver, register it in DriverRegistry before calling Init via its registration API, or supply an IComponentFactory to the ApplicationImpl before Init.
4. Check for typos and casing: names are matched exactly by DriverRegistry.TryGetDriver.

Example fix

// before
app.Init ("Win32");

// after
app.Init ("Windows");
// or let it auto-detect:
app.Init ();

string driver = "Windows";
if (DriverRegistry.TryGetDriver (driver, out _))
{
    app.Init (driver);
}
else
{
    app.Init (); // fall back to platform default
}

static bool IsValidDriverName (string name) =>
    DriverRegistry.TryGetDriver (name, out _);

When it happens

Trigger: Calling app.Init("MyCustomDriver") or Application.Create().Init("foo") with an unregistered name; setting ForceDriver to an unknown value (e.g. via config or the GUIRESOURCES env var); misspelling a driver name like "Win32" instead of "Windows" or "dotnet" casing issues.

Common situations: Copy-pasting a driver name from outdated v1 documentation or forum posts; migrating from v1 where driver names differed; setting the FORCE_DRIVER environment variable / ForceDriver property to an experimental value; typos in configuration JSON.

Related errors

• DefaultKeyBindings dictionary is null. Initialize it before
• Driver not initialized. Call Init() first.
• Theme cannot be set before ConfigurationManager is initializ
• Failed to set screenBuffer console mode, error code: {Marsha
• Failed to get input console mode, error code: {GetLastError(

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/d6108ef365210195. Report an issue: GitHub.