{"record":{"id":"f5a7c1ea4b62a5a3","repo":"karatelabs/karate","slug":"start-argument-must-be-a-string-path-or-config-map","errorCode":null,"errorMessage":"start() argument must be a string path or config map","messagePattern":"start\\(\\) argument must be a string path or config map","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/KarateJs.java","lineNumber":975,"sourceCode":"                    builder.port(((Number) config.get(\"port\")).intValue());\n                }\n                if (config.containsKey(\"ssl\")) {\n                    builder.ssl(Boolean.TRUE.equals(config.get(\"ssl\")));\n                }\n                if (config.containsKey(\"cert\")) {\n                    builder.certPath((String) config.get(\"cert\"));\n                }\n                if (config.containsKey(\"key\")) {\n                    builder.keyPath((String) config.get(\"key\"));\n                }\n                if (config.containsKey(\"arg\")) {\n                    builder.arg((Map<String, Object>) config.get(\"arg\"));\n                }\n                if (config.containsKey(\"pathPrefix\")) {\n                    builder.pathPrefix((String) config.get(\"pathPrefix\"));\n                }\n            } else {\n                throw new RuntimeException(\"start() argument must be a string path or config map\");\n            }\n\n            return builder.start();\n        };\n    }\n\n    /**\n     * karate.proceed() - Forward the current request to a target URL (proxy mode).\n     * Can only be used within a mock scenario.\n     * Usage:\n     * <pre>\n     * // Forward to specific target\n     * var response = karate.proceed('http://backend:8080');\n     *\n     * // Forward using Host header from request\n     * var response = karate.proceed();\n     * </pre>\n     */","sourceCodeStart":957,"sourceCodeEnd":993,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/KarateJs.java#L957-L993","documentation":"karate.start() starts an embedded MockServer from within a JS block. It accepts exactly two shapes of arguments: a string path to a feature file (karate.start('api.feature')) or a config map with a 'mock' key (karate.start({mock: 'api.feature', port: 8080})). Karate throws this error when the argument is neither a String nor a Map — the library cannot interpret any other type as a mock definition.","triggerScenarios":"Calling karate.start() with an argument that is not a string and not a Map — e.g. karate.start(8080), karate.start(['api.feature']), karate.start(someJavaObject), or a JS object that arrives as a non-Map bridged type.","commonSituations":"Developers assume start() takes a port number like MockServer.builder(); or they pass an array of feature paths expecting multiple mocks to start; or a variable holding the feature path was accidentally overwritten with a non-string value in the scenario.","solutions":["Pass a string path to the feature file: karate.start('api.feature')","Pass a config map with a 'mock' key: karate.start({mock: 'api.feature', port: 8080})","If passing a variable, confirm it holds a string path (print it before calling start())","To start multiple mocks, call karate.start() once per feature path instead of passing an array"],"exampleFix":"// before\nvar port = 8080;\nvar server = karate.start(port); // fails: number is not a path or map\n\n// after\nvar server = karate.start({ mock: 'api.feature', port: 8080 });","handlingStrategy":"validation","validationCode":"// JS in scenario\nvar arg = /* value to pass */;\nif (typeof arg !== 'string' && (typeof arg !== 'object' || arg === null || Array.isArray(arg))) {\n  throw new Error('karate.start() needs a feature path string or a config map, got: ' + typeof arg);\n}\nvar server = karate.start(arg);","typeGuard":"function isStartArg(v) {\n  return typeof v === 'string' || (v !== null && !Array.isArray(v) && typeof v === 'object');\n}","tryCatchPattern":"try {\n  var server = karate.start(arg);\n} catch (e) {\n  if (('' + e).indexOf('must be a string path or config map') !== -1) {\n    karate.log('bad start() argument, expected string path or {mock: ...} map');\n  }\n  throw e;\n}","preventionTips":["Always pass a quoted feature path string or an object literal with a 'mock' key","Never pass a port number directly — put it in the config map's 'port' key","Print the variable with karate.log before passing it if it was built dynamically"],"tags":["javascript","mock-server","invalid-argument","karate"],"backgroundTag":"invalid-argument-value","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}