SP_KoboldCpp:
SP_KoboldCpp connects a ComfyUI workflow to a running KoboldCpp text-generation service. It sends your instructions to the selected language model and brings the response back into the workflow, where you can use it for tasks such as developing image concepts, drafting descriptions, or refining prompt ideas. It supports several conversation formats and generation presets, so you can match the request to the model and choose a style of response. It can also send images for vision tasks when the model supports them.
SP_KoboldCpp Input Parameters:
api_url
The address of the KoboldCpp service the node will contact. The node appends /generate to this address, so enter the service’s base URL rather than the full generation endpoint. Its default comes from the package’s API_URL setting; the supplied source does not show that address. No minimum or maximum length is specified. An incorrect address or a service that is not running will prevent the request from completing.
system_prompt
Background instructions that guide how the model responds, such as its role, tone, or task boundaries. The selected conversation format incorporates these instructions into the request sent to KoboldCpp. The default comes from the package’s system_prompt setting, whose text is not included in the supplied source. No length limits are specified. Clear, consistent instructions can help keep generated descriptions or prompt ideas aligned with your intended style.
prompt
The main request you want the model to answer. For example, you might ask for three variations of an image concept or a concise description of a scene. The selected conversation format prepares this text before sending it to KoboldCpp, so the format can affect how the model interprets it. The default is an empty string, and no length limits are specified.
llm_mode
Selects the conversation format used to prepare the request, including how instructions and the prompt are arranged and which stop sequences are sent. Choose a format appropriate for the model loaded in KoboldCpp; a mismatch can produce poorly structured replies. The available options are KoboldCppAuto, Chat, Alpaca, ChatML, CommandR, DeepSeek25, Gemma23, GLM4, Llama2Chat, Llama3Chat, Llama4Chat, Metharme, MistralNonTekken, MistralTekken, Phi3Mini, Vicuna, OpenaiHarmony, QuestionAnswer, and InputOutput. The source does not explicitly declare a default selection or describe the formatting rules for each option.
preset
Selects a bundled set of sampling settings, which influence qualities such as variety and repetition in the generated text. The options are simple_logical, default, simple_balanced, simple_creative, silly_tavern, coherent_creativity, godlike, and liminal_drift. The source does not explicitly declare a default selection. The bundled simple_logical settings use a lower temperature of 0.25, while simple_creative uses 1; these can be useful starting points for more restrained or more varied responses, respectively. An attached override_cfg can change settings after the preset is applied.
max_length
Controls the maximum generated length sent to KoboldCpp. It is an integer from 0 to 8192, with a default of 0. When set to 0, the node does not add max_length to its request, leaving that limit to the service’s behavior. A positive value is sent as the limit; smaller values can keep answers brief, while larger values allow longer responses. The actual amount of text can also depend on the model and its stop conditions.
seed
The integer sent as KoboldCpp’s sampler_seed. It ranges from 0 to 18446744073709551615 and defaults to 0. Setting the same seed can help you compare changes to prompts or presets, although identical results also depend on the model and other generation settings. The supplied source does not establish any special meaning for the default value of 0.
override_cfg
An optional OVERRIDE_CFG connection that applies configuration changes to the request after the selected preset has been added. Use it when you need finer control than a preset provides. Because it is applied before max_length, banned_tokens, and images are processed, those inputs may subsequently set their corresponding request fields. Its available settings and defaults depend on the connected configuration node and are not defined here.
banned_tokens
An optional BANNED_TOKENS connection that supplies tokens to exclude from generation. When connected, its value replaces the request’s initially empty banned-token list. This can help restrict unwanted output, but overly broad restrictions may make a response less useful. The supplied source does not define the connected node’s token format or individual defaults.
images
An optional IMAGE input for an image or batch of images to include with the request. The node converts each image to PNG and sends it to KoboldCpp as encoded image data. Connect this input only when the loaded model supports vision; otherwise, its answer may be unreliable or it may not handle the image as intended. No image-size limit or default image is specified in the supplied source.
SP_KoboldCpp Output Parameters:
text
The generated response as a STRING. On a successful request, the node takes the first result returned by KoboldCpp and removes occurrences of User: from that text. You can pass this output to later workflow steps that consume text. If KoboldCpp returns a non-200 HTTP status, this output instead contains a message in the form ``Error:
``; check it before treating the value as generated content.
payload
A STRING containing an indented JSON representation of the request settings and content sent by the node. It is useful for checking the selected format, preset settings, length limit, banned tokens, and any included images when troubleshooting or comparing runs. This is the request payload, not a second generated answer, and it is returned even when the service responds with a non-200 status. Be careful when sharing it: it can include your prompt, instructions, and encoded image data.
SP_KoboldCpp Usage Tips:
- Start by confirming that KoboldCpp is running and that
api_urlpoints to its base address. The node will add/generateitself. - Match
llm_modeto the format expected by your loaded model. If replies contain unwanted role labels or seem to ignore instructions, check this setting before changing the creative content of your prompt. - Use
simple_logicalas a starting point for concise, restrained descriptions andsimple_creativewhen exploring more varied ideas. Compare results with the same prompt and seed to judge the preset’s effect. - Set a positive
max_lengthwhen you need a bounded response, such as a short image prompt. Leave it at 0 when you want the service to determine the limit. - Connect
imagesonly for a vision-capable model, and ask a specific question about what you want it to inspect. The presence of an image alone does not establish that the model can interpret it. - Inspect
payloadwhen a result differs from expectations. It shows the settings actually assembled for the request, including changes made throughoverride_cfg.
SP_KoboldCpp Common Errors and Solutions:
Error: 404 - …
- Explanation: KoboldCpp returned a “not found” response. The node sends requests to
<api_url>/generate, so the address may point to the wrong service or already include an endpoint path. - Solution: Check the base address in
api_url, remove an extra/generateif present, and confirm that the running service exposes the expected endpoint.
Error: 400 - … or Error: 422 - …
- Explanation: The service rejected the request. The details after the status code come from the service and may identify an unsupported setting, image, or request format.
- Solution: Read the full error text, then check
llm_mode, any connectedoverride_cfgorbanned_tokens, and whether the loaded model accepts images. Retry with optional connections removed to narrow down the cause.
Error: 500 - … or Error: 503 - …
- Explanation: The service reported an internal error or was unavailable while processing the request. The node passes the service’s status and response text through as
text. - Solution: Check the KoboldCpp service and its logs, confirm that a model is loaded, and retry with a shorter request or without images if the service is under strain.
ConnectionError or Connection refused
- Explanation: The request could not reach the address in
api_url. This may occur when KoboldCpp is stopped, the address or port is wrong, or the service is inaccessible from the machine running ComfyUI. - Solution: Start or restart KoboldCpp, verify its address and port, and confirm that ComfyUI can reach it. This connection failure may appear as a node execution error rather than a returned
Error: …string.
KeyError: 'results' or KeyError: 'text'
- Explanation: The service returned HTTP 200, but its JSON response did not contain the fields the node expects:
results[0].text. - Solution: Confirm that
api_urlpoints to a compatible KoboldCpp generation endpoint. Inspect the service response or logs for an unexpected response format.
IndexError: list index out of range
- Explanation: The node expects at least one item in the response’s
resultslist, but the list may be empty. - Solution: Check the KoboldCpp logs and model state, then retry a simple text-only prompt. If it persists, inspect whether the service is returning generation results in the expected format.
ValueError or image conversion error
- Explanation: The node converts each supplied image into a PNG before sending it. An image with an unexpected shape or incompatible data may fail during conversion.
- Solution: Test with one standard ComfyUI image and remove other image-processing steps temporarily. Add the image batch back after the single-image request works.
