semaphoreui/semaphore · error

invalid format of arguments, must be valid JSON array or map

Error message

invalid format of arguments, must be valid JSON array or map: %v

What it means

Returned by convertArgsJSONIfArray in services/tasks/local_executor.go when the arguments JSON string is neither a JSON array of strings nor a JSON object of the shape map[string][]string. The function first tries to unmarshal as []string, then as the map form; failing both means the input does not match either accepted schema (mixed types, object values that are not string arrays, or syntactically invalid JSON). The %v embeds the last unmarshal error showing why the map parse failed.

Solutions

1. Use a plain JSON string array like ["arg1","arg2"] or a named-arguments object like {"default":["arg1"],"env":["x=1"]}
2. Ensure every value in the object form is itself an array of strings, not a bare string or number
3. Paste the arguments into a JSON validator to find the syntax error (quotes, commas, brackets)
4. Fix or normalise the stored arguments string, then retry the task

When it happens

Trigger: Thrown at services/tasks/local_executor.go:674 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of semaphoreui/semaphore@1774ccb71a (2026-09-07). Data as JSON: /api/errors/d65d27d1c7865ca4. Report an issue: GitHub.

Appendix: source

Thrown at services/tasks/local_executor.go:674

func convertArgsJSONIfArray(argsJSON string) (map[string][]string, error) {
	if argsJSON == "" {
		return nil, nil
	}

	// Try to parse as array first
	var arr []string
	if err := json.Unmarshal([]byte(argsJSON), &arr); err == nil {
		// It's an array, convert to map format
		mapArgs := map[string][]string{
			"default": arr,
		}
		return mapArgs, nil
	}

	// If not an array, verify it's a valid map format
	var mapArgs map[string][]string
	if err := json.Unmarshal([]byte(argsJSON), &mapArgs); err != nil {
		return nil, fmt.Errorf("invalid format of arguments, must be valid JSON array or map: %v", err)
	}

	return mapArgs, nil
}

// getCLIArgsMap returns args that support both array and map formats
// Array format is automatically converted to map with "default" key for backward compatibility
// Returns: templateArgsMap (map), taskArgsMap (map), err
func (t *LocalExecutor) getCLIArgsMap() (templateArgsMap map[string][]string, taskArgsMap map[string][]string, err error) {

	// Convert template arguments if needed
	if t.Template.Arguments != nil {
		templateArgsMap, err = convertArgsJSONIfArray(*t.Template.Arguments)
		if err != nil {
			return nil, nil, err
		}
	}

View on GitHub (pinned to 1774ccb71a)