{"id":"d2c67ee7d4c054e5","repo":"gin-gonic/gin","slug":"url-parameters-can-not-be-used-when-serving-a-stat","errorCode":null,"errorMessage":"URL parameters can not be used when serving a static file","messagePattern":"URL parameters can not be used when serving a static file","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"routergroup.go","lineNumber":183,"sourceCode":"// router.StaticFile(\"favicon.ico\", \"./resources/favicon.ico\")\nfunc (group *RouterGroup) StaticFile(relativePath, filepath string) IRoutes {\n\treturn group.staticFileHandler(relativePath, func(c *Context) {\n\t\tc.File(filepath)\n\t})\n}\n\n// StaticFileFS works just like `StaticFile` but a custom `http.FileSystem` can be used instead.\n// router.StaticFileFS(\"favicon.ico\", \"./resources/favicon.ico\", Dir{\".\", false})\n// Gin by default uses: gin.Dir()\nfunc (group *RouterGroup) StaticFileFS(relativePath, filepath string, fs http.FileSystem) IRoutes {\n\treturn group.staticFileHandler(relativePath, func(c *Context) {\n\t\tc.FileFromFS(filepath, fs)\n\t})\n}\n\nfunc (group *RouterGroup) staticFileHandler(relativePath string, handler HandlerFunc) IRoutes {\n\tif strings.Contains(relativePath, \":\") || strings.Contains(relativePath, \"*\") {\n\t\tpanic(\"URL parameters can not be used when serving a static file\")\n\t}\n\tgroup.GET(relativePath, handler)\n\tgroup.HEAD(relativePath, handler)\n\treturn group.returnObj()\n}\n\n// Static serves files from the given file system root.\n// Internally a http.FileServer is used, therefore http.NotFound is used instead\n// of the Router's NotFound handler.\n// To use the operating system's file system implementation,\n// use :\n//\n//\trouter.Static(\"/static\", \"/var/www\")\nfunc (group *RouterGroup) Static(relativePath, root string) IRoutes {\n\treturn group.StaticFS(relativePath, Dir(root, false))\n}\n\n// StaticFS works just like `Static()` but a custom `http.FileSystem` can be used instead.","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/gin-gonic/gin/blob/34dac209ffb6ef85cc78c5d217bbb7ad001d68fd/routergroup.go#L165-L201","documentation":"staticFileHandler (routergroup.go:183) panics when the relativePath passed to StaticFile / StaticFileFS contains ':' or '*', because static file routes serve a fixed path and URL parameters are meaningless there. The check runs at registration time, so this surfaces during server startup.","triggerScenarios":"router.StaticFile(\"/assets/:name\", file) — trying to parametrise a static file route; router.StaticFile(\"/files/*path\", file) — wildcard on a single-file route.","commonSituations":"Confusing StaticFile (one fixed file) with Static/StaticFS (a directory tree that supports /*filepath); trying to use path params on a static file handler.","solutions":["For a single fixed file use a literal path with no params: router.StaticFile(\"/favicon.ico\", \"./public/favicon.ico\").","For dynamic per-request files use a normal GET handler with c.Param and c.File(filepath.Join(...)).","For a directory tree use router.Static(\"/assets\", \"./public\") which handles /*filepath internally."],"exampleFix":"// before\nrouter.StaticFile(\"/assets/:name\", \"./public/logo.png\")\n// after\nrouter.StaticFile(\"/assets/logo.png\", \"./public/logo.png\")\n// or for dynamic:\nrouter.GET(\"/assets/:name\", func(c *gin.Context) {\n    c.File(filepath.Join(\"./public\", c.Param(\"name\")))\n})","handlingStrategy":"validation","validationCode":"if strings.ContainsAny(relativePath, \":*\") {\n    log.Fatalf(\"static file path %q must not contain URL parameters\", relativePath)\n}\nrouter.StaticFile(relativePath, filepath)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use literal paths for StaticFile (no : or *).","Reach for Static/StaticFS when you need to serve a directory tree.","Write a normal GET handler with c.Param for dynamic single-file responses."],"tags":["router","static","startup","panic","go"],"analyzedSha":"34dac209ffb6ef85cc78c5d217bbb7ad001d68fd","analyzedAt":"2026-08-04T21:26:18.438Z","schemaVersion":2}