nextcloud/server · error · OCSException

could not enable bundle

Error message

could not enable bundle

What it means

OCSException (HTTP 500) thrown by ApiController::enableBundle when getBundleByIdentifier succeeds but installing the bundle's apps (installAppBundle) throws a regular Exception (not BadMethodCallException). Maintenance mode is toggled around the install and reset in finally, and the failing exception is logged as 'could not enable bundle' with the bundleId.

Source

Thrown at apps/appstore/lib/Controller/ApiController.php:293

	 *
	 * @param string $bundleId - The bundle to enable
	 * @return DataResponse<Http::STATUS_OK, array{}, array{}>
	 * @throws OCSException - if the bundle, or one app within, could not be enabled
	 *
	 * 200: Bundle successfully enabled
	 */
	#[PasswordConfirmationRequired(strict: true)]
	#[ApiRoute(verb: 'POST', url: '/api/v1/bundles/enable')]
	public function enableBundle(string $bundleId): DataResponse {
		try {
			$bundle = $this->bundleFetcher->getBundleByIdentifier($bundleId);
			$this->config->setSystemValue('maintenance', true);
			$this->installer->installAppBundle($bundle);
		} catch (\BadMethodCallException $e) {
			throw new OCSNotFoundException('Bundle not found', $e);
		} catch (\Exception $exception) {
			$this->logger->error('could not enable bundle', ['bundleId' => $bundleId, 'exception' => $exception]);
			throw new OCSException('could not enable bundle', Http::STATUS_INTERNAL_SERVER_ERROR, $exception);
		} finally {
			$this->config->setSystemValue('maintenance', false);
		}

		return new DataResponse([]);
	}

	/**
	 * Convert URL to proxied URL so CSP is no problem
	 */
	private function createProxyPreviewUrl(string $url): string {
		if ($url === '') {
			return '';
		}

		return 'https://usercontent.apps.nextcloud.com/' . base64_encode($url);
	}

View on GitHub (pinned to ecdeb153ff)

Solutions

  1. Read nextcloud.log for 'could not enable bundle' — the chained exception identifies which bundled app failed
  2. Enable the bundle's apps individually to isolate the failing one and address its specific requirement/permission issue
  3. Verify app store reachability and apps/ writability, then retry the bundle
  4. If maintenance mode remains on after a fatal, clear it with `occ maintenance:mode --off`
Defensive patterns

Strategy: try-catch

Try / catch

try {
	await axios.post(generateOcsUrl('/apps/appstore/bundles/enable'), { bundleId })
} catch (e) {
	// 500 'could not enable bundle' — the log entry 'could not enable bundle' names the failing app
	// fallback: enable the bundle's apps individually to isolate the culprit
}

Prevention

When it happens

Trigger: POST /ocs/appstore/bundles/enable where any app inside the bundle fails to download, extract, or enable — same root causes as single-app enable failures: no appstore egress, apps/ not writable, PHP/NC version constraints of one bundled app unmet.

Common situations: Offline/air-gapped servers; restrictive apps/ permissions; one app in the bundle incompatible with the server version; partial bundle install on retry because earlier apps already installed.

Related errors

AI-assisted analysis of nextcloud/server@ecdeb153ff (2026-08-17). Data as JSON: /api/errors/3b3129514bba9bf1. Report an issue: GitHub.