Fix JS client private-Space connections (hf_token alias) and replace raw TypeErrors/unhandled rejections with clear errors (#13657)

* Fix JS client private-Space auth and error handling (hf_token alias, no more raw 'map' TypeErrors / unhandled rejections)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Address Copilot review: trim space_id, slash-tolerant named endpoint lookup, queue flag from skip_queue

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: trigger CI

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: abidlabs

.changeset/hip-pans-punch.md

@@ -0,0 +1,5 @@
+---
+"@gradio/client": patch
+---
+
+Fix private Space connections and error handling in the JS client: accept the deprecated `hf_token` option as an alias for `token`, raise clear errors when a Space is private or missing, tolerate malformed `/info` payloads instead of crashing with "Cannot read properties of undefined (reading 'map')", and make `predict()` reject with real `Error` objects instead of plain status objects that surface as unhandled promise rejections.

client/js/src/client.ts

@@ -25,6 +25,7 @@ import { submit } from "./utils/submit";
 import { RE_SPACE_NAME, process_endpoint } from "./helpers/api_info";
 import {
 	map_names_to_ids,
+	normalise_token_option,
 	resolve_cookies,
 	resolve_config,
 	get_jwt,
@@ -200,6 +201,7 @@ export class Client {
 		if (!options.events) {
 			options.events = ["data"];
 		}
+		normalise_token_option(options);
 
 		this.options = options;
 		this.current_payload = {};
@@ -230,8 +232,9 @@ export class Client {
 			await this.resolve_cookies();
 		}
 
-		await this._resolve_config().then(({ config }) =>
-			this._resolve_heartbeat(config)
+		await this._resolve_config().then(
+			(res: { config: Config } | undefined) =>
+				res?.config && this._resolve_heartbeat(res.config)
 		);
 
 		try {
@@ -400,7 +403,7 @@ export class Client {
 						load_status: "error",
 						detail: "NOT_FOUND"
 					});
-				throw Error(e);
+				throw e instanceof Error ? e : new Error(String(e));
 			}
 		}
 	}

client/js/src/constants.ts

@@ -35,6 +35,16 @@ export const UNAUTHORIZED_MSG = "Not authorized to access this space. ";
 export const INVALID_CREDENTIALS_MSG = "Invalid credentials. Could not login. ";
 export const MISSING_CREDENTIALS_MSG =
 	"Login credentials are required to access this space.";
+export const PRIVATE_SPACE_MSG =
+	"Could not access this app (received a 401 response). If it is a private Hugging Face Space, pass a valid Hugging Face token to the `token` option of `Client.connect`. You can generate a token at https://huggingface.co/settings/tokens.";
+export const SPACE_NOT_FOUND_MSG = (space: string, status: number): string =>
+	`Space "${space}" could not be accessed (received a ${status} response from the Hugging Face API). ` +
+	"Check that the Space name is spelled correctly and that the Space exists. If the Space is private, " +
+	"pass a valid Hugging Face token to the `token` option of `Client.connect`. You can generate a token at https://huggingface.co/settings/tokens.";
+export const NO_API_INFO_MSG =
+	"No API information is available for this app. This can happen when the app's `/info` endpoint cannot be reached, or when the app is running a legacy version of Gradio that is not supported by this client. ";
+export const WS_PROTOCOL_MSG =
+	"This app appears to be running a legacy version of Gradio (3.x or earlier) that communicates over WebSockets, which is not supported by this version of @gradio/client. Please upgrade the app to a newer version of Gradio, or connect to it with @gradio/client version 0.x.";
 export const NODEJS_FS_ERROR_MSG =
 	"File system access is only available in Node.js environments";
 export const ROOT_URL_ERROR_MSG = "Root URL not found in client config";

client/js/src/helpers/api_info.ts

@@ -2,7 +2,8 @@ import {
 	HOST_URL,
 	INVALID_URL_MSG,
 	QUEUE_FULL_MSG,
-	SPACE_METADATA_ERROR_MSG
+	SPACE_METADATA_ERROR_MSG,
+	SPACE_NOT_FOUND_MSG
 } from "../constants";
 import type {
 	ApiData,
@@ -35,21 +36,36 @@ export async function process_endpoint(
 
 	if (RE_SPACE_NAME.test(_app_reference)) {
 		// app_reference is a HF space name
+		let res: Response;
 		try {
-			const res = await fetch(
+			res = await fetch(
 				`https://huggingface.co/api/spaces/${_app_reference}/${HOST_URL}`,
 				{ headers }
 			);
+		} catch (e) {
+			throw new Error(SPACE_METADATA_ERROR_MSG);
+		}
 
-			const _host = (await res.json()).host;
+		if (res.status === 401 || res.status === 404) {
+			// the space does not exist, or it is private and the request was made
+			// without (or with an invalid) token
+			throw new Error(SPACE_NOT_FOUND_MSG(_app_reference, res.status));
+		}
 
-			return {
-				space_id: app_reference,
-				...determine_protocol(_host)
-			};
+		let _host: string | undefined;
+		try {
+			_host = (await res.json()).host;
 		} catch (e) {
 			throw new Error(SPACE_METADATA_ERROR_MSG);
 		}
+		if (!_host) {
+			throw new Error(SPACE_METADATA_ERROR_MSG);
+		}
+
+		return {
+			space_id: _app_reference,
+			...determine_protocol(_host)
+		};
 	}
 
 	if (RE_SPACE_DOMAIN.test(_app_reference)) {
@@ -98,7 +114,13 @@ export function transform_api_info(
 			transformed_info[category] = {};
 
 			Object.entries(api_info[category]).forEach(
-				([endpoint, { parameters, returns }]) => {
+				([endpoint, endpoint_info]) => {
+					// Guard against malformed or legacy `/info` payloads that are
+					// missing `parameters`/`returns` so that we surface a usable API
+					// description instead of crashing with
+					// "Cannot read properties of undefined (reading 'map')".
+					const parameters = endpoint_info?.parameters ?? [];
+					const returns = endpoint_info?.returns ?? [];
 					const dependencyIndex =
 						config.dependencies.find(
 							(dep) =>
@@ -108,22 +130,24 @@ export function transform_api_info(
 						api_map[endpoint.replace("/", "")] ||
 						-1;
 
-					const dependencyTypes =
+					const dependency =
 						dependencyIndex !== -1
 							? config.dependencies.find((dep) => dep.id == dependencyIndex)
-									?.types
+							: undefined;
+
+					const dependencyTypes =
+						dependencyIndex !== -1
+							? dependency?.types
 							: { generator: false, cancel: false };
 
 					if (
-						dependencyIndex !== -1 &&
-						config.dependencies.find((dep) => dep.id == dependencyIndex)?.inputs
-							?.length !== parameters.length
+						dependency &&
+						Array.isArray(dependency.inputs) &&
+						dependency.inputs.length !== parameters.length
 					) {
-						const components = config.dependencies
-							.find((dep) => dep.id == dependencyIndex)!
-							.inputs.map(
-								(input) => config.components.find((c) => c.id === input)?.type
-							);
+						const components = dependency.inputs.map(
+							(input) => config.components.find((c) => c.id === input)?.type
+						);
 
 						try {
 							components.forEach((comp, idx) => {

client/js/src/helpers/init_helpers.ts

@@ -1,10 +1,11 @@
-import type { Config } from "../types";
+import type { ClientOptions, Config } from "../types";
 import {
 	CONFIG_ERROR_MSG,
 	CONFIG_URL,
 	INVALID_CREDENTIALS_MSG,
 	LOGIN_URL,
 	MISSING_CREDENTIALS_MSG,
+	PRIVATE_SPACE_MSG,
 	SPACE_METADATA_ERROR_MSG,
 	UNAUTHORIZED_MSG
 } from "../constants";
@@ -53,6 +54,22 @@ export async function get_jwt(
 	}
 }
 
+/**
+ * The `hf_token` option was renamed to `token`, but a lot of existing code
+ * (and the Python client) still uses `hf_token`. Accept it as an alias so
+ * that authenticated requests are not silently sent without credentials,
+ * which previously surfaced as "Could not resolve app config" errors when
+ * connecting to private Spaces.
+ */
+export function normalise_token_option(options: ClientOptions): void {
+	if (options.hf_token && !options.token) {
+		options.token = options.hf_token;
+		console.warn(
+			"The `hf_token` option has been renamed to `token`. Support for `hf_token` will be removed in a future version of @gradio/client."
+		);
+	}
+}
+
 export function map_names_to_ids(
 	fns: Config["dependencies"]
 ): Record<string, number> {
@@ -153,7 +170,14 @@ async function handleConfigResponse(
 	authorized: boolean
 ): Promise<Config> {
 	if (response?.status === 401 && !authorized) {
-		const error_data = await response.json();
+		let error_data: any = null;
+		try {
+			error_data = await response.json();
+		} catch (e) {
+			// Unauthenticated requests to private Spaces receive a non-JSON 401
+			// page from the Hugging Face proxy rather than a Gradio auth payload.
+			throw new Error(PRIVATE_SPACE_MSG);
+		}
 		const auth_message = error_data?.detail?.auth_message;
 		throw new Error(auth_message || MISSING_CREDENTIALS_MSG);
 	} else if (response?.status === 401 && authorized) {
@@ -172,7 +196,9 @@ async function handleConfigResponse(
 		throw new Error(UNAUTHORIZED_MSG);
 	}
 
-	throw new Error(CONFIG_ERROR_MSG);
+	throw new Error(
+		`${CONFIG_ERROR_MSG}(received status ${response?.status} when fetching the app config)`
+	);
 }
 
 export async function resolve_cookies(this: Client): Promise<void> {

client/js/src/test/api_info.test.ts

@@ -1,7 +1,7 @@
 import {
 	INVALID_URL_MSG,
 	QUEUE_FULL_MSG,
-	SPACE_METADATA_ERROR_MSG
+	SPACE_NOT_FOUND_MSG
 } from "../constants";
 import { beforeAll, afterEach, afterAll, it, expect, describe } from "vitest";
 import {
@@ -10,7 +10,8 @@ import {
 	get_type,
 	process_endpoint,
 	join_urls,
-	map_data_to_params
+	map_data_to_params,
+	transform_api_info
 } from "../helpers/api_info";
 import { initialise_server } from "./server";
 import { transformed_api_info } from "./test_data";
@@ -471,19 +472,13 @@ describe("process_endpoint", () => {
 		expect(result).toEqual(expected);
 	});
 
-	it("should throw an error when fetching space metadata fails", async () => {
+	it("should throw a clear error when the space does not exist or is private", async () => {
 		const app_reference = "hmb/bye_world";
 		const token = "hf_token";
 
-		try {
-			await process_endpoint(app_reference, token);
-		} catch (error) {
-			if (error instanceof Error) {
-				expect(error.message).toEqual(SPACE_METADATA_ERROR_MSG);
-			} else {
-				expect.fail("Error should not be unknown.");
-			}
-		}
+		await expect(process_endpoint(app_reference, token)).rejects.toThrow(
+			SPACE_NOT_FOUND_MSG(app_reference, 404)
+		);
 	});
 
 	it("should return the correct data when app_reference is a valid space domain", async () => {
@@ -699,3 +694,36 @@ describe("map_data_params", () => {
 		);
 	});
 });
+
+describe("transform_api_info", () => {
+	it("defaults parameters and returns to empty arrays when an endpoint entry is malformed", () => {
+		const api_info = {
+			named_endpoints: {
+				// missing `parameters` and `returns`, as returned by some legacy
+				// or misbehaving apps (see issue #10945)
+				"/predict": {}
+			},
+			unnamed_endpoints: {}
+		} as any;
+		const config = {
+			dependencies: [
+				{
+					id: 0,
+					api_name: "predict",
+					inputs: [1],
+					outputs: [2],
+					types: { generator: false, cancel: false }
+				}
+			],
+			components: [
+				{ id: 1, type: "textbox", props: {} },
+				{ id: 2, type: "textbox", props: {} }
+			]
+		} as any;
+
+		const result = transform_api_info(api_info, config, { predict: 0 });
+
+		expect(result.named_endpoints["/predict"].parameters).toEqual([]);
+		expect(result.named_endpoints["/predict"].returns).toEqual([]);
+	});
+});

client/js/src/test/init.test.ts

@@ -15,7 +15,7 @@ import {
 	response_api_info
 } from "./test_data";
 import { initialise_server } from "./server";
-import { SPACE_METADATA_ERROR_MSG } from "../constants";
+import { SPACE_NOT_FOUND_MSG } from "../constants";
 
 const app_reference = "hmb/hello_world";
 const broken_app_reference = "hmb/bye_world";
@@ -87,12 +87,28 @@ describe("Client class", () => {
 			});
 		});
 
+		test("connecting successfully to a private running app with the deprecated hf_token option", async () => {
+			const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+			const app = await Client.connect("hmb/secret_world", {
+				hf_token: "hf_123"
+			});
+
+			expect(app.config).toEqual({
+				...config_response,
+				root: "https://hmb-secret-world.hf.space"
+			});
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("`hf_token` option has been renamed")
+			);
+			warn.mockRestore();
+		});
+
 		test("unsuccessfully attempting to connect to a private running app", async () => {
 			await expect(
 				Client.connect("hmb/secret_world", {
 					token: "hf_bad_token"
 				})
-			).rejects.toThrowError(SPACE_METADATA_ERROR_MSG);
+			).rejects.toThrowError(SPACE_NOT_FOUND_MSG("hmb/secret_world", 401));
 		});
 
 		test("viewing the api info of a running app", async () => {
@@ -139,7 +155,9 @@ describe("Client class", () => {
 		test("creating a duplicate of a broken app", async () => {
 			const duplicate = Client.duplicate(broken_app_reference);
 
-			await expect(duplicate).rejects.toThrow(SPACE_METADATA_ERROR_MSG);
+			await expect(duplicate).rejects.toThrow(
+				SPACE_NOT_FOUND_MSG(broken_app_reference, 404)
+			);
 		});
 	});
 

client/js/src/test/submit.test.ts

@@ -162,8 +162,6 @@ describe("predict error handling", () => {
 				1000,
 				"predict() never settled for an unknown endpoint"
 			)
-		).rejects.toThrow(
-			"There is no endpoint matching that name of fn_index matching that number."
-		);
+		).rejects.toThrow('No endpoint matching "nonexistent_endpoint" was found');
 	});
 });

client/js/src/types.ts

@@ -323,6 +323,11 @@ export interface DuplicateOptions extends ClientOptions {
 
 export interface ClientOptions {
 	token?: `hf_${string}`;
+	/**
+	 * @deprecated Use `token` instead. Kept as an alias so that code written
+	 * for older versions of the client keeps working.
+	 */
+	hf_token?: `hf_${string}`;
 	status_callback?: SpaceStatusCallback | null;
 	auth?: [string, string] | null;
 	with_null_state?: boolean;

client/js/src/utils/duplicate.ts

@@ -8,6 +8,7 @@ import { Client } from "../client";
 import { SPACE_METADATA_ERROR_MSG } from "../constants";
 import {
 	get_cookie_header,
+	normalise_token_option,
 	parse_and_set_cookies
 } from "../helpers/init_helpers";
 import { process_endpoint } from "../helpers/api_info";
@@ -16,6 +17,7 @@ export async function duplicate(
 	app_reference: string,
 	options: DuplicateOptions
 ): Promise<Client> {
+	normalise_token_option(options);
 	const { token, private: _private, hardware, timeout, auth } = options;
 
 	if (hardware && !hardware_types.includes(hardware)) {