{"record":{"id":"71527c6ca4e17150","repo":"linera-io/linera-protocol","slug":"no-subscription-query-registered-with-name","errorCode":null,"errorMessage":"no subscription query registered with name '{}'","messagePattern":"no subscription query registered with name '(.+?)'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"linera-service/src/query_subscription.rs","lineNumber":125,"sourceCode":"\n    /// Returns the GraphQL query string for a given name, if registered.\n    pub fn get_query(&self, name: &str) -> Option<&str> {\n        self.queries.get(name).map(|s| s.as_str())\n    }\n\n    /// Returns a watch receiver for the given key. Lazily spawns a watcher if needed.\n    /// The receiver initially holds `None`; the watcher populates it with `Some(value)`\n    /// after the first query. Callers should filter out `None` values from the stream.\n    pub fn subscribe<C: ClientContext + 'static>(\n        self: &Arc<Self>,\n        key: &SubscriptionKey,\n        context: Arc<futures::lock::Mutex<C>>,\n        token: CancellationToken,\n    ) -> anyhow::Result<watch::Receiver<Option<String>>> {\n        let query_string = self\n            .get_query(&key.name)\n            .ok_or_else(|| {\n                anyhow::anyhow!(\"no subscription query registered with name '{}'\", key.name)\n            })?\n            .to_string();\n\n        let mut watchers = self.watchers.lock().unwrap();\n\n        // If a watcher already exists, reuse it.\n        if let Some(state) = watchers.get(key) {\n            return Ok(state.sender.subscribe());\n        }\n\n        // Create a new watch channel (initial value is None until the first query completes).\n        let (sender, receiver) = watch::channel(None);\n        watchers.insert(\n            key.clone(),\n            WatcherState {\n                sender: sender.clone(),\n            },\n        );","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/linera-io/linera-protocol/blob/6c226ddcb332ef55118dc8d0aafbd093d5420899/linera-service/src/query_subscription.rs#L107-L143","documentation":"QuerySubscriptionManager::subscribe resolves a SubscriptionKey (operation name + chain + application) against the queries registered at startup from --allow-subscription. This error means a subscription request referenced an operation name that is not in that registry, so there is no query string to run for the watcher.","triggerScenarios":"Sending a GraphQL subscription request to the node's service whose operation name was never registered, e.g. requesting 'Notifs' when the node was started with --allow-subscription 'query Notifications { ... }'. Raised from subscribe() itself or from run_query_subscription_watcher when re-subscribing.","commonSituations":"Node restarted without the --allow-subscription flag; typo or case mismatch between the requested operation name and the registered one; deploying a new client version that renames operations against an old node config; TTL config referencing one name while requests use another.","solutions":["Restart the node with --allow-subscription 'query <Name> { ... }' where <Name> exactly matches the name used in subscription requests (case-sensitive)","Verify the registry with QuerySubscriptionManager::get_query(name) (it returns Option) or by re-reading the startup flags","Check for case differences and trailing whitespace in the name on both the registration and the request side"],"exampleFix":"# before\nlinera ... (node started without the flag; client subscribes to 'Notifs')\n# after\nlinera ... --allow-subscription 'query Notifs { notifications { id } }'","handlingStrategy":"validation","validationCode":"// Rust: check registration before subscribing\nlet query = manager.get_query(&key.name);\nif query.is_none() {\n    return Err(anyhow!(\"subscription {name} not registered; restart node with --allow-subscription 'query {name} {{ ... }}'\", name = key.name));\n}","typeGuard":"fn is_registered(manager: &QuerySubscriptionManager, name: &str) -> bool {\n    manager.get_query(name).is_some()\n}","tryCatchPattern":"match manager.subscribe(&key, context, token).await {\n    Ok(rx) => { /* stream rx, skipping initial None */ }\n    Err(e) if e.to_string().contains(\"no subscription query registered\") => {\n        // surface as a config problem: name unknown to this node\n        return_service_error(StatusCode::NOT_FOUND, e);\n    }\n    Err(e) => return internal_error(e),\n}","preventionTips":["Keep the list of --allow-subscription values in version control next to the node launch scripts","Health-check endpoint: expose get_query(name) results so clients can verify names before subscribing","Use identical, case-sensitive operation names in registration flags, TTL config, and client code"],"tags":["linera","graphql","subscription","registry","node-config"],"backgroundTag":"unknown-operation-name","analyzedSha":"6c226ddcb332ef55118dc8d0aafbd093d5420899","analyzedAt":"2026-08-22T22:49:09.787Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}