Nextcloud Errors App

nextcloud-errors-app

Quick Diagnostic Index

Error 1: Namespace & Autoloading Failures

Symptom

OCP\AppFramework\QueryException: Could not resolve OCA\MyApp\Controller\PageController!
Class "OCA\MyApp\Service\ItemService" not found

Cause A: Missing <namespace> in info.xml

The <namespace> element in appinfo/info.xml tells Nextcloud's autoloader how to map OCA\{Namespace}\* to the lib/ directory. Without it, no classes are discoverable.

Fix:

<!-- appinfo/info.xml -->
<info>
    <id>myapp</id>
    <namespace>MyApp</namespace>
    <!-- ... -->
</info>

ALWAYS ensure the <namespace> value matches the second segment of your PHP namespace exactly: OCA\MyApp\* requires <namespace>MyApp</namespace>.

Cause B: Directory Structure Mismatch

Nextcloud maps OCA\{Namespace}\Controller\PageController to lib/Controller/PageController.php. A mismatch between namespace and file path causes autoload failure.

Fix: Verify the mapping:

NEVER place PHP classes outside the lib/ directory -- Nextcloud's autoloader only scans lib/.

Cause C: Case Sensitivity

Linux filesystems are case-sensitive. lib/controller/PageController.php will NOT match namespace OCA\MyApp\Controller\PageController.

Fix: ALWAYS match directory casing exactly to namespace casing.

Error 2: info.xml Validation Problems

Symptom

App rejected by app store, app not appearing after enable, or validation warnings in logs.

Cause A: Deprecated Fields

These fields cause validation failure on the Nextcloud app store:

Fix: NEVER use deprecated fields. ALWAYS use the <dependencies> block:

<dependencies>
    <nextcloud min-version="28" max-version="32"/>
    <php min-version="8.1"/>
</dependencies>

Cause B: Missing Required Fields

Minimum required fields for a valid info.xml:

<info xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="https://apps.nextcloud.com/schema/apps/info.xsd">
    <id>myapp</id>
    <name>My Application</name>
    <summary>Short description</summary>
    <description>Full description</description>
    <version>1.0.0</version>
    <licence>AGPL-3.0-or-later</licence>
    <author>Developer Name</author>
    <namespace>MyApp</namespace>
    <category>tools</category>
    <dependencies>
        <nextcloud min-version="28" max-version="32"/>
    </dependencies>
</info>

ALWAYS include both min-version AND max-version in the nextcloud dependency -- omitting either causes app store validation failure.

Cause C: Invalid Category

Valid categories: customization, files, games, integration, monitoring, multimedia, office, organization, security, social, tools.

Fix: NEVER use categories outside this list.

Cause D: Invalid <id> Format

The <id> field MUST contain only lowercase ASCII letters and underscores. No hyphens, no uppercase, no numbers at the start.

Error 3: Migration Errors

Symptom

Migration OCA\MyApp\Migration\Version1000Date20240101000000 already executed
An exception occurred while executing a query: ... duplicate column name

Cause A: Modifying an Executed Migration

Nextcloud tracks which migrations have run in the oc_migrations table. Once a migration executes, changing its code has NO effect -- or worse, causes schema conflicts.

Fix: NEVER modify existing migration files. ALWAYS create a new migration class for any schema change:

// NEW file: lib/Migration/Version1000Date20240201000000.php
class Version1000Date20240201000000 extends SimpleMigrationStep {
    public function changeSchema(IOutput $output, Closure $schemaClosure, array $options) {
        $schema = $schemaClosure();
        $table = $schema->getTable('myapp_items');
        if (!$table->hasColumn('new_column')) {
            $table->addColumn('new_column', Types::STRING, [
                'notnull' => false,
                'length' => 255,
            ]);
        }
        return $schema;
    }
}

Cause B: Wrong Naming Convention

Migration class names MUST follow: Version{MajorMinor}Date{YYYYMMDDHHmmss}.

Fix: ALWAYS use the correct version-to-number mapping: major * 1000 + minor.

Cause C: Missing Existence Checks

Running occ app:enable on an existing install without guarding against existing tables/columns causes crashes.

Fix: ALWAYS check before creating:

if (!$schema->hasTable('myapp_items')) {
    $table = $schema->createTable('myapp_items');
    // ...
}

// For columns on existing tables:
$table = $schema->getTable('myapp_items');
if (!$table->hasColumn('new_field')) {
    $table->addColumn('new_field', Types::STRING, ['notnull' => false]);
}

Cause D: Missing Primary Key

Tables without primary keys fail on Galera Cluster setups (used by many hosting providers).

Fix: ALWAYS add a primary key:

$table->addColumn('id', Types::BIGINT, ['autoincrement' => true, 'notnull' => true]);
$table->setPrimaryKey(['id']);

Error 4: Bootstrap Timing Violations

Symptom

Service not found / null service during app loading
Random "class not found" errors that resolve on reload
Intermittent failures depending on app load order

Cause: Querying Services in register()

The register() method is called during app loading BEFORE all apps have completed registration. Querying services from other apps here is unreliable.

Wrong:

public function register(IRegistrationContext $context): void {
    // WRONG: Other apps may not be registered yet
    $manager = \OCP\Server::get(ISomeManager::class);
    $manager->registerProvider(MyProvider::class);
}

Fix:

public function register(IRegistrationContext $context): void {
    // ONLY use IRegistrationContext methods here
    $context->registerEventListener(SomeEvent::class, MyListener::class);
    $context->registerMiddleware(MyMiddleware::class);
    $context->registerServiceAlias(IMyInterface::class, MyImpl::class);
}

public function boot(IBootContext $context): void {
    // Safe to query services here -- all apps are registered
    $context->injectFn(function (ISomeManager $manager) {
        $manager->registerProvider(MyProvider::class);
    });
}

Decision Tree: register() vs boot()

Need to register a service/listener/middleware?
  YES --> Use register() with IRegistrationContext methods ONLY
  NO --> Need to call methods on services from other apps?
    YES --> Use boot() with $context->injectFn()
    NO --> Need to set up runtime state?
      YES --> Use boot()
      NO --> You probably do not need Application.php at all

NEVER put business logic in Application.php -- keep it in Service/ classes.

NEVER use \OCP\Server::get() inside register() -- it is a service locator anti-pattern AND may fail due to load ordering.

Error 5: Dependency Injection Failures

Symptom

OCP\AppFramework\QueryException: Could not resolve parameter $someParam
Could not resolve type SomeInterface

Cause A: Missing Type Hint

Auto-wiring requires type hints on all constructor parameters. Untyped or primitively-typed parameters (except $appName, $userId, $webRoot) cannot be resolved.

Wrong:

class MyService {
    public function __construct(private $mapper) { }  // No type hint
}

Fix:

class MyService {
    public function __construct(private ItemMapper $mapper) { }
}

Cause B: Interface Without Alias

Auto-wiring resolves concrete classes automatically but cannot guess which implementation to use for an interface.

Fix: Register an alias in Application.php:

public function register(IRegistrationContext $context): void {
    $context->registerServiceAlias(IMyMapper::class, MyMapper::class);
}

Cause C: Unresolvable Primitive Parameters

Constructor parameters like string $tableName or int $maxRetries cannot be auto-wired (except the predefined $appName, $userId, $webRoot).

Fix: Register the parameter explicitly:

public function register(IRegistrationContext $context): void {
    $context->registerParameter('tableName', 'myapp_items');
}

Or use a factory:

$context->registerService(MyMapper::class, function (ContainerInterface $c) {
    return new MyMapper($c->get(IDBConnection::class), 'myapp_items');
});

Cause D: Optional Dependency Not Nullable

When depending on a service from another app that may not be installed, a non-nullable type hint causes a fatal error.

Fix: ALWAYS use nullable types for optional dependencies:

class MyService {
    public function __construct(private ?OptionalService $optional) { }

    public function doWork(): void {
        if ($this->optional !== null) {
            $this->optional->integrate();
        }
    }
}

Error 6: Deprecated API Usage

Symptom

OCP\ILogger is deprecated since Nextcloud 24
Using \OCP\Server::get() is discouraged
Legacy hook system warnings

Deprecated: OCP\ILogger

Since: NC 24

Wrong:

use OCP\ILogger;

class MyService {
    public function __construct(private ILogger $logger) { }
}

Fix: ALWAYS use PSR-3 LoggerInterface:

use Psr\Log\LoggerInterface;

class MyService {
    public function __construct(private LoggerInterface $logger) { }

    public function process(): void {
        $this->logger->info('Processing started');
        $this->logger->error('Failed', ['exception' => $e]);
    }
}

Deprecated: \OCP\Server::get()

Wrong:

$userManager = \OCP\Server::get(IUserManager::class);

Fix: ALWAYS use constructor injection:

class MyService {
    public function __construct(private IUserManager $userManager) { }
}

Deprecated: Legacy Hooks

Wrong:

$userManager->listen('\OC\User', 'postDelete', function ($user) { });

Fix: ALWAYS use typed events with IRegistrationContext:

// In Application::register()
$context->registerEventListener(
    UserDeletedEvent::class,
    UserDeletedListener::class
);

Deprecated: GenericEvent

Since: NC 22

Wrong:

use OCP\EventDispatcher\GenericEvent;
$dispatcher->dispatch('my.event', new GenericEvent($subject, $args));

Fix: ALWAYS create typed event classes:

class ItemCreatedEvent extends \OCP\EventDispatcher\Event {
    public function __construct(private string $itemId) {
        parent::__construct();
    }
    public function getItemId(): string { return $this->itemId; }
}

// Dispatch
$dispatcher->dispatchTyped(new ItemCreatedEvent($id));

Deprecated: database.xml

Fix: NEVER use database.xml for new apps. ALWAYS use migrations in lib/Migration/.

Deprecated: requiremin/requiremax in info.xml

Fix: ALWAYS use the <dependencies> block instead. See Error 2.

Critical Rules Summary

Reference Links

• references/methods.md -- Error types, exception classes, diagnostic methods
• references/examples.md -- Error scenarios with complete fixes
• references/anti-patterns.md -- App development mistakes to avoid

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/app_development/info.html
• https://docs.nextcloud.com/server/latest/developer_manual/app_development/bootstrap.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/dependency_injection.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/events.html