What causes "Failed to create processor '{0}'" in MonoGame/MonoGame?

Add the processor's assembly via manager.AddAssembly(absPath).

MonoGame/MonoGame · error · PipelineException

Failed to create processor '{0}'

Error message

Failed to create processor '{0}'

What it means

ProcessContent instantiates the processor via CreateProcessor(name, parameters) after a successful import. If that returns null (processor type not found among loaded assemblies, name null/empty, or could not be constructed), processing aborts with PipelineException. The importer succeeded; only the processor side is broken.

Source

Thrown at MonoGame.Framework.Content.Pipeline/PipelineBuilder/PipelineManager.cs:869

                {
                    throw new PipelineException($"Importer '{pipelineEvent.Importer}' had unexpected failure!", inner);
                }
            }
            else
            {
                var importContext = new PipelineImporterContext(this, pipelineEvent);
                using var _ = ContextScopeFactory.BeginContext(importContext, pipelineEvent);
                importedObject = importer.Import(pipelineEvent.SourceFile, importContext);
            }

            // The pipelineEvent.Processor can be null or empty. In this case the
            // asset should be imported but not processed.
            if (string.IsNullOrEmpty(pipelineEvent.Processor))
                return importedObject;

            var processor = CreateProcessor(pipelineEvent.Processor, pipelineEvent.Parameters);
            if (processor == null)
                throw new PipelineException("Failed to create processor '{0}'", pipelineEvent.Processor);

            // Make sure the input type is valid.
            if (!processor.InputType.IsAssignableFrom(importedObject.GetType()))
            {
                throw new PipelineException($"The type '{importedObject.GetType().FullName}' cannot be processed by {pipelineEvent.Processor} as a {processor.InputType.FullName}!");
            }

            // Process the imported object.

            object processedObject;
            if (RethrowExceptions)
            {
                try
                {
                    var processContext = new PipelineProcessorContext(this, pipelineEvent);
                    using var _ = ContextScopeFactory.BeginContext(processContext);
                    processedObject = processor.Process(importedObject, processContext);
                }

View on GitHub (pinned to 1d71bbd0ff)

Solutions

Add the processor's assembly via manager.AddAssembly(absPath).
Confirm pipelineEvent.Processor matches the processor type name exactly (and DisplayName).
Check pipeline host log for assembly-load failures for the processor's assembly.
Rebuild/reinstall the processor package against the current MonoGame.Content.Pipeline version.

Example fix

// before:
//   // processor lives in a separate assembly not registered
//   manager.ProcessContent(ev);
//
// after:
//   manager.AddAssembly(Path.GetFullPath("ext/MyProcessors.dll"));
//   manager.ProcessContent(ev);

Defensive patterns

Strategy: validation

Validate before calling

if (manager.GetProcessorType(ev.Processor) == null)
    throw new InvalidOperationException(
        $"Processor '{ev.Processor}' not found. Register its assembly via AddAssembly.");

manager.ProcessContent(ev);

Try / catch

try { var o = manager.ProcessContent(ev); }
catch (PipelineException ex) when (ex.Message.StartsWith("Failed to create processor"))
{ logger.Error($"Unknown processor '{ev.Processor}'. Did you AddAssembly its DLL?"); }

Prevention

Register processor assemblies alongside their importers at startup.
Verify processor names match the type/DisplayName in .mgcb rows.
Surface assembly-load warnings so missing processors are caught early.

When it happens

Trigger: pipelineEvent.Processor names a processor type CreateProcessor cannot resolve (assembly not registered, name mismatch, namespace change) or is null/empty while a processor was expected (it is non-empty so it passed the IsNullOrEmpty early-return). Throw at PipelineManager.cs:869.

Common situations: Processor assembly not added via AddAssembly; processor class renamed or moved in a new version; .mgcb references a processor from a package that was uninstalled; constructor of the processor threw during reflection-based instantiation causing null.

Related errors

AI-assisted analysis of MonoGame/MonoGame@1d71bbd0ff (2026-08-13). Data as JSON: /api/errors/d7a09adc74e403cf. Report an issue: GitHub.