can1357/oh-my-pi · error · Error

owncloud share response did not include an OCS envelope

Error message

owncloud share response did not include an OCS envelope

What it means

ownCloudShare validates that the share API response contains the OCS envelope (an `ocs` key wrapping `meta` and `data`) and throws when it does not. ownCloud's OCS API normally returns { ocs: { meta, data } }; a response lacking this structure means the endpoint answered but not with an OCS-encoded share payload.

Source

Thrown at packages/coding-agent/src/blob-broker/uploaders-self-hosted.ts:51

	downloadBase?: string;
}

interface PlikFile {
	id: string;
	name?: string;
}

function nonEmptyString(value: unknown): string | undefined {
	return typeof value === "string" && value.length > 0 ? value : undefined;
}

function identifier(value: unknown): string | undefined {
	return typeof value === "string" || typeof value === "number" ? String(value) : undefined;
}

function ownCloudShare(value: unknown): OwnCloudShare {
	if (typeof value !== "object" || value === null || !("ocs" in value)) {
		throw new Error("owncloud share response did not include an OCS envelope");
	}
	const ocs = value.ocs;
	if (typeof ocs !== "object" || ocs === null || !("meta" in ocs) || !("data" in ocs)) {
		throw new Error("owncloud share response did not include OCS metadata and data");
	}
	const meta = ocs.meta;
	const data = ocs.data;
	if (typeof meta !== "object" || meta === null || !("statuscode" in meta)) {
		throw new Error("owncloud share response did not include an OCS status");
	}
	if (typeof data !== "object" || data === null || !("url" in data)) {
		throw new Error("owncloud share response did not include a URL");
	}
	const url = nonEmptyString(data.url);
	if (!url) throw new Error("owncloud share response did not include a URL");
	const id = "id" in data ? identifier(data.id) : undefined;
	return { statusCode: meta.statuscode, url, ...(id ? { id } : {}) };
}

View on GitHub (pinned to 9690622007)

Solutions

1. Confirm the share endpoint URL is the OCS one (…/ocs/v2.php/apps/files_sharing/api/v1/shares) and that Accept/format=json is set.
2. Check authentication: a failed login often returns an HTML page without the ocs envelope; verify app password/token.
3. Log the raw response body to see whether it is HTML (auth/redirect issue) or bare JSON (envelope-mode issue).
4. Try adding OCS-APIRequest: true header, required by many ownCloud versions to return the OCS envelope.

Example fix

// before
await fetch(`${base}/remote.php/dav/files/`, { method: "POST", headers: { Authorization: auth } });
// after
await fetch(`${base}/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json`, {
  method: "POST",
  headers: { Authorization: auth, "OCS-APIRequest": "true" },
  body: form,
});

const res = await fetch(shareUrl, { headers: { "OCS-APIRequest": "true", Accept: "application/json", Authorization: auth } });
const body = await res.json();
if (typeof body !== "object" || body === null || !("ocs" in body)) {
  throw new Error(`non-OCS response from share endpoint: ${JSON.stringify(body).slice(0, 200)}`);
}

function isOcsEnvelope(v: unknown): v is { ocs: { meta: unknown; data: unknown } } {
  if (typeof v !== "object" || v === null || !("ocs" in v)) return false;
  const ocs = (v as { ocs: unknown }).ocs;
  return typeof ocs === "object" && ocs !== null && "meta" in ocs && "data" in ocs;
}

try {
  const share = await share(destination, request);
} catch (err) {
  if (err instanceof Error && err.message.includes("OCS envelope")) {
    logger.error("ownCloud share endpoint returned non-OCS body; check URL/auth/OCS-APIRequest header", { err });
  } else throw err;
}

When it happens

Trigger: POSTing to the ownCloud share endpoint (share.php/ocs/v1.php or v2) returns JSON/XML without an `ocs` wrapper — e.g. the server returned a plain WebDAV/HTML error, the URL targets the non-OCS share endpoint, or OCS envelope wrapping is disabled (`OCS_API` returned bare data in some v2 configurations).

Common situations: Wrong share URL (missing /ocs/v2.php path); ownCloud server returning an HTML login/redirect page because auth failed; server configured with 'show server outline'/bare-JSON mode so the ocs wrapper is absent; hitting Nextcloud vs ownCloud path differences.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• owncloud share response did not include OCS metadata and dat
• owncloud share response did not include an OCS status
• owncloud share response did not include a URL
• Gemini Files API ${context} response is not valid JSON
• Gemini Files API finalize response is missing ${field}

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/5775059a067bb907. Report an issue: GitHub.