juicedata/juicefs · error

ErrFuncTimeout

ErrFuncTimeout

Error message

function timeout

What it means

utils.ErrFuncTimeout signals that a wrapped function exceeded its deadline. It is treated as a first-class cancellation: chunk reads propagate it, and the disk cache treats it like an I/O failure, marking the cache store unavailable.

Source

Thrown at pkg/utils/errors.go:26

 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package utils

import (
	"errors"
	"syscall"
)

var (
	ErrNotSUP      = errors.New("not supported")
	ErrFuncTimeout = errors.New("function timeout")
	ErrSkipped     = errors.New("skipped")
	ErrExtlink     = syscall.Errno(1000)
)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Increase the relevant timeout configuration or reduce load
2. Check the cache disk health (smartctl/dmesg) and replace if it is failing — the cache is put into a degraded state on this error
3. Investigate slow upstream storage/network causing the deadline breach
4. Retry; transient slowness may clear after the cache recovers

Example fix

// before
result, err := utils.WithTimeout(func(ctx context.Context) (...) { ... }, timeout)
// after
result, err := utils.WithTimeout(func(ctx context.Context) (...) { ... }, timeout*2) // raise timeout for slow disks

// check cache disk writable and has space before heavy reads
if st, err := os.Stat(cacheDir); err != nil || !st.IsDir() {
	logger.Warnf("cache dir unavailable: %v", err)
}

func isTimeout(err error) bool { return errors.Is(err, utils.ErrFuncTimeout) }

n, err := cs.Read(ctx, key, p, off)
if errors.Is(err, utils.ErrFuncTimeout) {
	// propagate or retry with backoff after cache recovers
	return 0, err
}

When it happens

Trigger: A cached_store read or disk-cache operation wrapped in utils.WithTimeout exceeds its deadline; the timeout error then flows back through Read and cache handling.

Common situations: Slow or failing cache disk causing operations to hit the timeout; overloaded object storage increasing latency past configured limits.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• invalid hour number
• space not enough on device
• concurrent staging limit reached
• not supported
• error GET request: %v

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/ba4ba50946073278. Report an issue: GitHub.