{"record":{"id":"fc9b6621355f20b6","repo":"wavetermdev/waveterm","slug":"setting-background-v","errorCode":null,"errorMessage":"setting background: %v","messagePattern":"setting background: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/wsh/cmd/wshcmd-setbg.go","lineNumber":225,"sourceCode":"\n\t// Resolve tab reference\n\tid := blockArg\n\tif id == \"\" {\n\t\tid = \"tab\"\n\t}\n\toRef, err := resolveSimpleId(id)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// Send RPC request\n\tsetMetaWshCmd := wshrpc.CommandSetMetaData{\n\t\tORef: *oRef,\n\t\tMeta: meta,\n\t}\n\terr = wshclient.SetMetaCommand(RpcClient, setMetaWshCmd, &wshrpc.RpcOpts{Timeout: 2000})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"setting background: %v\", err)\n\t}\n\n\tWriteStdout(\"background set\\n\")\n\treturn nil\n}\n","sourceCodeStart":207,"sourceCodeEnd":231,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-setbg.go#L207-L231","documentation":"After building the metadata, setbg sends it to the running Wave Terminal via the SetMetaCommand wsh RPC with a 2-second timeout. Any RPC failure — no connected terminal, connection dropped, remote not reachable, timeout, or server-side rejection — is wrapped as \"setting background\". The local validation succeeded but the change was not applied.","triggerScenarios":"Running `wsh setbg` outside a Wave Terminal context (no block/tab connection), the terminal connection dropped mid-command, the target tab/block (resolved via --block or the default \"tab\") is gone, or the RPC exceeded the 2000ms timeout because the terminal is hung or on a slow remote (SSH) connection.","commonSituations":"Running wsh from a plain system shell not attached to Wave; stale block ID passed with --block after closing that block; slow SSH remotes timing out; waveterm backend restarting during the call.","solutions":["Run the command from inside a Wave Terminal block (wsh requires an active connection)","Retry the command — transient network/timeout issues often resolve on a second attempt","Verify the block ID passed with --block still exists in the current window","Check the Wave Terminal connection is alive (try another wsh command like `wsh ls`)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"# confirm you are inside a waveterm-connected context first\nwsh ls / >/dev/null 2>&1 || { echo \"wsh has no terminal connection\" >&2; exit 1; }","typeGuard":null,"tryCatchPattern":"const { execSync } = require(\"child_process\");\nfor (let attempt = 1; attempt <= 3; attempt++) {\n  try { execSync(`wsh setbg \"${img}\"`); break; }\n  catch (e) {\n    if (String(e.stderr).includes(\"setting background\") && attempt < 3) continue;\n    throw e;\n  }\n}","preventionTips":["Run wsh from inside a Wave Terminal block, not a detached system shell","Verify the --block target exists before calling setbg","Retry once on timeout — SSH remotes can transiently exceed the 2s RPC limit","Keep the terminal connection healthy (wsh ls as a ping)"],"tags":["cli","rpc","network","waveterm"],"backgroundTag":"rpc-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}