{"record":{"id":"1d865882bc66ad76","repo":"overleaf/overleaf","slug":"this-file-cannot-be-refreshed","errorCode":null,"errorMessage":"This file cannot be refreshed","messagePattern":"This file cannot be refreshed","errorType":"http","errorClass":"FileCannotRefreshError","httpStatus":400,"severity":"warning","filePath":"services/web/app/src/Features/LinkedFiles/LinkedFilesController.mjs","lineNumber":258,"sourceCode":"      )\n    } else if (error instanceof NotOriginalImporterError) {\n      res.status(400)\n      plainTextResponse(\n        res,\n        'You are not the user who originally imported this file'\n      )\n    } else if (error instanceof FeatureNotAvailableError) {\n      res.status(400)\n      plainTextResponse(res, 'This feature is not enabled on your account')\n    } else if (error instanceof RemoteServiceError) {\n      if (error.info?.statusCode === 403) {\n        res.status(400).json({ relink: true })\n      } else {\n        res.status(502)\n        plainTextResponse(res, 'The remote service produced an error')\n      }\n    } else if (error instanceof FileCannotRefreshError) {\n      res.status(400)\n      plainTextResponse(res, 'This file cannot be refreshed')\n    } else if (error.message === 'project_has_too_many_files') {\n      res.status(400)\n      plainTextResponse(res, 'too many files')\n    } else if (/\\bECONNREFUSED\\b/.test(error.message)) {\n      res.status(500)\n      plainTextResponse(res, 'Importing references is not currently available')\n    } else if (error instanceof FileTooLargeError) {\n      res.status(422)\n      plainTextResponse(res, 'File too large')\n    } else {\n      next(error)\n    }\n  },\n}\n","sourceCodeStart":240,"sourceCodeEnd":274,"githubUrl":"https://github.com/overleaf/overleaf/blob/28ad3b03b71cb4311decdcb55c36b33ec10d72db/services/web/app/src/Features/LinkedFiles/LinkedFilesController.mjs#L240-L274","documentation":"handleError recognizes an instance of FileCannotRefreshError and returns 400 'This file cannot be refreshed'. The domain layer raises this when a linked file's refresh operation is not permitted in its current state (e.g. the file is no longer linked, was deleted remotely, or lacks a refreshable source). It is a deliberate business-rule rejection, not an unexpected fault.","triggerScenarios":"A POST/refresh request on a linked file whose provider state makes refresh impossible, causing the service layer to reject with FileCannotRefreshError which handleError converts to a 400 plain-text response.","commonSituations":"User tries to refresh a file whose remote counterpart was deleted or access revoked, file created by a deprecated provider, stale link after provider-side policy change.","solutions":["Check the linked file's status/provider before attempting refresh","Ask the user to relink or re-import the file if the link is stale","Remove or archive the broken linked file","Verify the provider still exposes the underlying file"],"exampleFix":"// before\nfetch(`/linkedservice/refresh/${fileId}`)\n// after: pre-check link status client-side\nconst { status } = await fetch(`/linkedservice/status/${fileId}`).then(r => r.json())\nif (status !== 'linked') showRelinkPrompt()\nelse fetch(`/linkedservice/refresh/${fileId}`)","handlingStrategy":"validation","validationCode":"const link = await getLinkedFileStatus(fileId)\nif (!link || link.status !== 'linked') {\n  throw new Error('file is not refreshable; relink first')\n}","typeGuard":"function canRefresh(link) {\n  return link != null && link.status === 'linked' && typeof link.providerId === 'string'\n}","tryCatchPattern":"try {\n  await refreshLinkedFile(fileId)\n} catch (e) {\n  if (e instanceof FileCannotRefreshError) return showRelinkUI()\n  throw e\n}","preventionTips":["Check link/provider status before offering the refresh action","Disable refresh buttons for unlinked or deleted remote files","Handle relink flow proactively on 403 responses","Periodically reconcile linked-file state with the provider"],"tags":["business-rule","linked-files","http-400"],"backgroundTag":"file-refresh-not-allowed","analyzedSha":"28ad3b03b71cb4311decdcb55c36b33ec10d72db","analyzedAt":"2026-09-03T02:10:22.807Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}