{"id":"79582fbd7db83f28","repo":"gin-gonic/gin","slug":"url-parameters-can-not-be-used-when-serving-a-stat-79582f","errorCode":null,"errorMessage":"URL parameters can not be used when serving a static folder","messagePattern":"URL parameters can not be used when serving a static folder","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"routergroup.go","lineNumber":205,"sourceCode":"\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.\n// Gin by default uses: gin.Dir()\nfunc (group *RouterGroup) StaticFS(relativePath string, fs http.FileSystem) IRoutes {\n\tif strings.Contains(relativePath, \":\") || strings.Contains(relativePath, \"*\") {\n\t\tpanic(\"URL parameters can not be used when serving a static folder\")\n\t}\n\thandler := group.createStaticHandler(relativePath, fs)\n\turlPattern := path.Join(relativePath, \"/*filepath\")\n\n\t// Register GET and HEAD handlers\n\tgroup.GET(urlPattern, handler)\n\tgroup.HEAD(urlPattern, handler)\n\treturn group.returnObj()\n}\n\nfunc (group *RouterGroup) createStaticHandler(relativePath string, fs http.FileSystem) HandlerFunc {\n\tabsolutePath := group.calculateAbsolutePath(relativePath)\n\tfileServer := http.StripPrefix(absolutePath, http.FileServer(fs))\n\n\treturn func(c *Context) {\n\t\tif _, noListing := fs.(*OnlyFilesFS); noListing {\n\t\t\tc.Writer.WriteHeader(http.StatusNotFound)\n\t\t}","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/gin-gonic/gin/blob/34dac209ffb6ef85cc78c5d217bbb7ad001d68fd/routergroup.go#L187-L223","documentation":"StaticFS (routergroup.go:205) panics when the relativePath contains ':' or '*', because StaticFS itself registers a /*filepath wildcard under the hood to serve directory contents. A user-supplied ':' or '*' would collide with Gin's own wildcard and break routing, so Gin rejects it at registration time.","triggerScenarios":"router.Static(\"/static/:dir\", \"./public\") or router.StaticFS(\"/files/*name\", fs) — passing a param/wildcard segment to a folder-serving route.","commonSituations":"Confusing Static (folder) with StaticFile (single file); trying to inject path params into a static directory mount; building the path from user input that happens to contain a colon.","solutions":["Mount the folder on a plain prefix with no params: router.Static(\"/static\", \"./public\").","To serve per-user folders, register a GET handler with c.Param and a custom http.FileServer, or chain groups (router.Group(\"/user/:id\").Static(\"/files\", dir)).","If you need parametrised static files, write an explicit handler instead of Static/StaticFS."],"exampleFix":"// before\nrouter.Static(\"/static/:bucket\", \"./public\")\n// after\nrouter.Static(\"/static\", \"./public\")\n// or parametrised:\nrouter.GET(\"/:bucket/*filepath\", func(c *gin.Context) {\n    c.FileFromFS(filepath.Join(c.Param(\"bucket\"), c.Param(\"filepath\")), http.Dir(\"./public\"))\n})","handlingStrategy":"validation","validationCode":"if strings.ContainsAny(relativePath, \":*\") {\n    log.Fatalf(\"static folder path %q must not contain URL parameters\", relativePath)\n}\nrouter.StaticFS(relativePath, fs)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Mount Static/StaticFS on plain prefixes (no : or *).","For per-user folders, write a custom GET handler with c.Param.","Remember StaticFS already adds /*filepath internally — don't add your own wildcard."],"tags":["router","static","staticfs","startup","panic","go"],"analyzedSha":"34dac209ffb6ef85cc78c5d217bbb7ad001d68fd","analyzedAt":"2026-08-04T21:26:18.438Z","schemaVersion":2}